SQLITE_IOERR_MMAPERRORTier 2 — Caution⚠️ MEDIUM confidenceI/O error during memory-mapped file access
Category: I/O ErrorVersions: 3.7.17+
🔴 Production Risk Error
High — may cause SIGBUS (process crash) rather than a graceful error.
What this means
SQLITE_IOERR_MMAP (6154) is returned when an error occurs while reading from a memory-mapped region of the database file, typically a SIGBUS due to an underlying I/O error.
Why it happens
- 1Hardware failure causing a SIGBUS on mmap read.
- 2NFS disconnect while the file is memory-mapped.
- 3File truncated externally while mmap is active.
How to reproduce
mmap-mode reads (PRAGMA mmap_size > 0) when the underlying file has I/O errors.
trigger — this will ERROR
import sqlite3
conn = sqlite3.connect('my.db')
conn.execute('PRAGMA mmap_size=268435456') # 256 MB mmap
# If disk fails while reading mmap region → SQLITE_IOERR_MMAPsqlite3.DatabaseError: disk I/O error
Fix 1
Why this works
Disable mmap if on unreliable storage: PRAGMA mmap_size=0
Fix 2
Why this works
Check disk health.
Fix 3
Why this works
Use traditional read mode on network filesystems.
What not to do
✗
Why it's wrong:
Version notes
Sources
📚 Official docs: https://www.sqlite.org/rescode.html#ioerr_mmap
🔧 Source ref: sqlite3.h — SQLITE_IOERR_MMAP = 6154
📖 Further reading: SQLite mmap I/O
Confidence assessment
⚠️ MEDIUM confidence
Stable.
See also
📄 Reference pages
SQLite mmap I/O
⚙️ This error reference was generated with AI assistance and reviewed for accuracy. Examples are provided to illustrate common scenarios and may not cover every case. Always test fixes in a development environment before applying to production. Spotted an error? Suggest a correction →