disk I/O error
Production Risk
SQLITE_IOERR in production almost always means the database file is in an unknown state. Immediately stop writes, take a file-system backup of the .db and .db-wal files, run PRAGMA integrity_check, and restore from a verified backup if corruption is found.
SQLITE_IOERR (result code 10) is returned when the SQLite VFS layer encounters an unexpected error from the operating system during a read or write to the database file, WAL file, or journal file. It almost always indicates a hardware or OS-level problem — full disk, failing drive, NFS timeout, or a permissions error on a file that was already open.
- 1The filesystem has run out of disk space mid-write
- 2A network filesystem (NFS, CIFS) disconnected during a transaction
- 3The storage device is reporting I/O errors (failing SSD or HDD)
- 4The application process lost write permission on the database file after the connection was opened
- 5Antivirus or security software intercepting and blocking file writes
The disk fills up completely during a large INSERT, preventing the journal from being written.
# This cannot be easily demonstrated in :memory: mode.
# In a real environment, fill the disk and then attempt a write:
import sqlite3
conn = sqlite3.connect('/mnt/nearly-full/demo.db')
# When disk fills during commit:
# sqlite3.OperationalError: disk I/O errorexpected output
sqlite3.OperationalError: disk I/O error
Fix 1
Free disk space and retry
WHEN When a full filesystem is the root cause.
import shutil
total, used, free = shutil.disk_usage('/')
print(f"Free: {free // (1024**3)} GB")
# Free space by deleting temp files, then reconnect and retry.Why this works
SQLITE_IOERR is a hard error that cannot be resolved at the SQL level — it requires fixing the underlying OS or hardware condition. After recovery, the database may need integrity checking.
Fix 2
Run integrity check after recovery
WHEN After resolving the underlying I/O error, verify the database is not corrupted.
import sqlite3
conn = sqlite3.connect('mydb.db')
result = conn.execute('PRAGMA integrity_check').fetchall()
print(result) # [('ok',)] if healthyWhy this works
integrity_check traverses all pages of the database B-tree and verifies structural consistency. If the I/O error interrupted a write mid-page, this will reveal corruption that requires restore from backup.
✕ Continue using the database after SQLITE_IOERR without an integrity check
An interrupted write may have left a page partially written, silently corrupting data that will only surface as incorrect query results later.
SQLITE_IOERR has over 20 extended codes (e.g. SQLITE_IOERR_READ=266, SQLITE_IOERR_WRITE=778) that identify which VFS operation failed.
sqlite3.h — SQLITE_IOERR = 10
SQLite VFS documentation ↗SQLite atomic commit ↗Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev