SQLITE_BUSY: database is locked
Another connection holds a lock SQLite needs, usually a writer in another process. Set a busy timeout, keep write transactions short, or switch to WAL mode.
- Result code
SQLITE_BUSY- Name
5- Category
- Primary result codes
What it means
SQLite allows one writer at a time per database file. When a connection needs a lock that another connection (in the same or another process) holds, the call fails with SQLITE_BUSY and the message database is locked, unless a busy handler is set, in which case SQLite retries for up to the timeout first.
By default there is no busy handler, so the failure is immediate. In rollback-journal mode readers also block a writer from committing, and a writer blocks new readers while it commits; WAL mode lets readers and one writer work at the same time.
Common causes
- Two processes or threads write to the same database at the same time, with no busy timeout set.
- A long write transaction (or a
BEGINthat was never committed) holds the lock while others wait. - A read transaction started with
BEGIN DEFERREDtries to upgrade to a write while another connection is writing; in WAL mode this returnsSQLITE_BUSY_SNAPSHOTand waiting won't help. - An open cursor or unfinished statement in your own program keeps a read transaction open.
- The database file is on a network file system whose locking doesn't work reliably.
How to fix it
-
Set a busy timeout so SQLite waits and retries instead of failing at once. Most bindings expose it (Python's
sqlite3waits 5 seconds by default; raise it withsqlite3.connect(path, timeout=30)). In SQL:PRAGMA busy_timeout = 5000; -- milliseconds
-
Switch the database to write-ahead logging, so readers no longer block the writer and the writer doesn't block readers.
PRAGMA journal_mode = WAL;
-
Start write transactions with
BEGIN IMMEDIATE, which takes the write lock up front. A busy connection then waits atBEGIN(where the timeout applies) instead of failing halfway through.BEGIN IMMEDIATE; UPDATE counters SET n = n + 1 WHERE name = 'visits'; COMMIT;
-
Keep transactions short, commit promptly, and finish or reset every statement (close cursors) so no connection holds a lock longer than it needs.
-
Keep the database on a local disk, not a network share.
Reproduce it safely
Use two separate connections to the same scratch database file.
-- Connection 1 (for example the sqlite3 shell): BEGIN IMMEDIATE; INSERT INTO t VALUES (1); -- Connection 2, same file, no busy timeout: INSERT INTO t VALUES (2); -- Runtime error: database is locked (5)
Questions
What is the difference between SQLITE_BUSY and SQLITE_LOCKED?
SQLITE_BUSY means another database connection, usually in another process, holds a conflicting lock. SQLITE_LOCKED means the conflict is inside your own connection or between connections sharing a cache, for example dropping a table while a statement is still reading it.
Does WAL mode get rid of database is locked?
It removes most reader-writer conflicts, but there is still only one writer at a time, so concurrent writers still need a busy timeout.
Related errors
SQLITE_LOCKEDdatabase table is lockedSQLITE_BUSY_SNAPSHOTstale read can't become a writeSQLITE_BUSY_TIMEOUTblocking file lock timed out55P03PostgreSQL: lock not available1205MySQL: Lock wait timeout exceeded1222SQL Server: Lock request time out period exceeded
More primary result codes errors
SQLITE_ERRORSQL logic errorSQLITE_PERMaccess permission deniedSQLITE_ABORTquery abortedSQLITE_NOMEMout of memorySQLITE_READONLYattempt to write a readonly databaseSQLITE_INTERRUPTinterruptedSQLITE_IOERRdisk I/O errorSQLITE_CORRUPTdatabase disk image is malformed
The code and message text are from the SQLite result and error codes documentation. Browse the full SQLite error list or search every database error.
Work on SQLite in SQLly
A native SQL client for macOS, Windows and Linux with schema-aware IntelliSense, guardrails for risky statements and clear error messages, for SQLite and the other databases you use.