disk I/O error (write failure)
Production Risk
A write failure in the middle of a journal sync leaves the journal in an incomplete state. On next open, SQLite will attempt a rollback; if the rollback also fails, the database may be permanently inconsistent. Always back up before any recovery attempt.
SQLITE_IOERR_WRITE (extended code 778) is the specific I/O error returned when the write() system call on the database file, WAL, or journal fails. Unlike a generic IOERR this directly identifies that a write could not be completed, which has more severe implications for database integrity than a read failure.
- 1The filesystem has run out of space and the OS returned ENOSPC from write()
- 2A network filesystem disconnect caused the write to fail
- 3Hardware-level write error from a failing storage device
- 4The file was deleted or its permissions changed while the connection was open
A write fails partway through a journal sync on a full filesystem.
# Cannot be reliably triggered in Python without filesystem manipulation.
# In production: monitor for sqlite3.OperationalError with 'disk I/O error'
# and check extended error code with conn.execute("PRAGMA last_error_code")expected output
sqlite3.OperationalError: disk I/O error
Fix
Monitor disk space proactively
WHEN In production environments to prevent IOERR_WRITE before it occurs.
import shutil, sqlite3
def check_db_disk_space(db_path, min_free_mb=500):
stat = shutil.disk_usage(db_path)
free_mb = stat.free // (1024 * 1024)
if free_mb < min_free_mb:
raise RuntimeError(f"Low disk space: {free_mb}MB free on {db_path}")Why this works
Proactive disk space monitoring allows the application to stop writes and alert before the filesystem becomes completely full, preventing mid-write failures that can leave the journal in an inconsistent state.
✕ Retry the write immediately after SQLITE_IOERR_WRITE
If the write failed due to a full disk, immediate retry will fail again. If it failed due to a hardware error, retrying may corrupt partially-written pages further.
Extended code 778 documented in sqlite3.h.
Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev