// SQLite error reference

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
Error message
database is locked

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 BEGIN that was never committed) holds the lock while others wait.
  • A read transaction started with BEGIN DEFERRED tries to upgrade to a write while another connection is writing; in WAL mode this returns SQLITE_BUSY_SNAPSHOT and 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

  1. Set a busy timeout so SQLite waits and retries instead of failing at once. Most bindings expose it (Python's sqlite3 waits 5 seconds by default; raise it with sqlite3.connect(path, timeout=30)). In SQL:

    PRAGMA busy_timeout = 5000;  -- milliseconds
  2. 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;
  3. Start write transactions with BEGIN IMMEDIATE, which takes the write lock up front. A busy connection then waits at BEGIN (where the timeout applies) instead of failing halfway through.

    BEGIN IMMEDIATE;
    UPDATE counters SET n = n + 1 WHERE name = 'visits';
    COMMIT;
  4. Keep transactions short, commit promptly, and finish or reset every statement (close cursors) so no connection holds a lock longer than it needs.

  5. 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

More primary result codes errors

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.

// fewer errors, faster fixes

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.