database concurrency_error ai_generated true

sqlite3.OperationalError: database is locked

ID: database/sqlite-locked

Also available as: JSON · Markdown
88%Fix Rate
90%Confidence
82Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
3 active — — —

Root Cause

Another connection or process holds a lock on the SQLite database file, preventing the current operation. SQLite uses file-level locking and supports only one writer at a time. Common in web applications, multi-threaded programs, or when the database is on a network filesystem.

generic

Workarounds

  1. 90% success Enable WAL (Write-Ahead Logging) mode for better concurrency 
    Run: PRAGMA journal_mode=WAL; This allows concurrent readers with a single writer (instead of exclusive locks for both). Set once per database; it persists. Also set a busy timeout: PRAGMA busy_timeout=5000; (5 seconds) to automatically retry when locked.
  2. 85% success Serialize write access through a single connection or connection pool 
    Use a single database connection for all writes, or use a connection pool with max_size=1 for write operations. In Python: sqlite3.connect('db.sqlite3', check_same_thread=False) with a threading.Lock() around write operations. For Django, use DATABASE_OPTIONS {'timeout': 20}.

Dead Ends

Common approaches that don't work:

  1. Using SQLite for high-concurrency web applications with multiple writer processes 85% fail

    SQLite's single-writer architecture fundamentally cannot handle concurrent writes from multiple processes. No configuration change can overcome this limitation. This is a design constraint, not a bug.

  2. Placing the SQLite database on a network filesystem (NFS, SMB, CIFS) 90% fail

    SQLite's locking mechanism relies on POSIX file locks which do not work correctly on many network filesystems. This leads to database corruption and persistent locking errors that cannot be fixed by retry logic.

Error Chain

Leads to:
Preceded by:
Frequently confused with: