node database_error ai_generated true

Error: SQLITE_BUSY: database is locked

ID: node/sqlite-busy-database-locked

Also available as: JSON · Markdown
85%Fix Rate
88%Confidence
85Evidence
2019-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
20 active — — —

Root Cause

SQLite database is locked by another connection or process. Common in Node.js apps using better-sqlite3 or sqlite3 with concurrent writes, especially in serverless environments or when WAL mode is not enabled.

generic

Workarounds

  1. 90% success Enable WAL (Write-Ahead Logging) mode for concurrent read/write 
    db.pragma('journal_mode = WAL');
// Or for sqlite3 package:
db.run('PRAGMA journal_mode=WAL;');

    Sources: https://www.sqlite.org/wal.html

  2. 88% success Use a single shared database connection with a write queue 
    Serialize all write operations through a single connection. Use a queue (e.g., p-queue with concurrency=1) to ensure only one write happens at a time.

    Sources: https://github.com/WiseLibs/better-sqlite3/blob/master/docs/threads.md

  3. 82% success Set busy_timeout to wait for locks instead of failing immediately 
    db.pragma('busy_timeout = 5000');
// Waits up to 5 seconds for the lock to be released

    Sources: https://www.sqlite.org/pragma.html#pragma_busy_timeout

Dead Ends

Common approaches that don't work:

  1. Adding retry loops with short delays to wait for the lock 60% fail

    Retries can work for occasional contention, but under sustained concurrent writes, retries create thundering herd problems and increase latency without solving the root cause.

  2. Opening multiple database connections for parallel writes 85% fail

    SQLite only allows one writer at a time regardless of how many connections are open. Multiple connections increase lock contention.

Error Chain

Frequently confused with: