disk I/O error (write failure)

Category: I/O ErrorVersions: SQLite 3.7.17+

🔴 Production Risk Error

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.

What this means

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.

Why it happens

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

How to reproduce

A write fails partway through a journal sync on a full filesystem.

trigger — this will ERROR

# 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")

sqlite3.OperationalError: disk I/O error

Fix 1: Monitor disk space proactively

In production environments to prevent IOERR_WRITE before it occurs.

fix

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.

What not to do

✗

Retry the write immediately after SQLITE_IOERR_WRITE

Why it's wrong: 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.

Version notes

SQLite 3.7.17+Extended code 778 documented in sqlite3.h.

Sources

📚 Official docs: https://www.sqlite.org/rescode.html#ioerr_write

🔧 Source ref: sqlite3.h — SQLITE_IOERR_WRITE = 778

📖 Further reading: SQLite atomic commit

Confidence assessment

✅ HIGH confidence

Extended code is documented in sqlite3.h. Production risk description aligns with SQLite atomiccommit documentation.