SQLITE_BUSY_TIMEOUTERRORTier 2 — Caution⚠️ MEDIUM confidenceBusy: timeout waiting for lock
Category: LockingVersions: 3.38.0+
🔴 Production Risk Error
Medium — transaction must be retried.
What this means
SQLITE_BUSY_TIMEOUT (773) is returned by the multiplexed VFS (SQLITE_ENABLE_SETLK_TIMEOUT) when a lock wait times out. It distinguishes a timeout from other busy conditions.
Why it happens
- 1Lock acquisition timed out because another connection holds the lock.
- 2Used with the SQLITE_ENABLE_SETLK_TIMEOUT build option and blocking locks.
How to reproduce
Blocking lock waits in configurations built with SQLITE_ENABLE_SETLK_TIMEOUT.
trigger — this will ERROR
# SQLITE_BUSY_TIMEOUT is raised when the OS-level lock wait times out
# Retry logic is the same as SQLITE_BUSYsqlite3.OperationalError: database is locked (timeout)
Fix 1
Why this works
Increase the lock timeout via sqlite3_busy_timeout() or the timeout= parameter.
Fix 2
Why this works
Retry the transaction with exponential backoff.
Version notes
Sources
📚 Official docs: https://www.sqlite.org/rescode.html#busy_timeout
🔧 Source ref: sqlite3.h — SQLITE_BUSY_TIMEOUT = 773
Confidence assessment
⚠️ MEDIUM confidence
Stable. Requires specific build option.
See also
🔗 Related errors
📄 Reference pages
sqlite3_busy_timeout
⚙️ 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 →