Fix "database is locked" in SQLite
Why SQLite says database is locked, why a busy timeout sometimes does not help, and the fixes: BEGIN IMMEDIATE, WAL mode and closing stray transactions.
Quick Answer
Another connection holds a lock SQLite needs, and your connection gave up waiting. In most apps the fix is three settings: wait instead of failing, let readers and the writer work at the same time, and start write transactions with BEGIN IMMEDIATE:
PRAGMA busy_timeout = 5000; -- wait up to 5 s for a lock (per connection)
PRAGMA journal_mode = WAL; -- readers no longer block the writer (persists in the file)
BEGIN IMMEDIATE; -- take the write lock up front, not halfway through
UPDATE accounts SET balance = balance - 10 WHERE id = 1;
COMMIT;
If it still happens, something is holding a transaction open: a forgotten commit(), a half-read cursor, or a GUI with uncommitted edits.
What the error means
SQLite allows many readers but only one writer per database file. When a connection needs a lock that another connection holds, SQLite returns result code 5, SQLITE_BUSY, which every client reports as "database is locked". Each client words it slightly differently:
| Client | What you see | Default wait |
|---|---|---|
| sqlite3 CLI | Error: stepping, database is locked (5), exit status 5 | None: fails instantly |
| Python sqlite3 | sqlite3.OperationalError: database is locked, e.sqlite_errorname == "SQLITE_BUSY" (3.11+) | 5 s (timeout=5.0) |
| Node better-sqlite3 | SqliteError with err.code === "SQLITE_BUSY" | 5 s (timeout: 5000) |
A different message, database table is locked (code 6, SQLITE_LOCKED), comes from inside one connection, for example dropping a table while a SELECT on it is still being read. Finish or close the cursor first.
In VisuaLeaf
Avoid leaving a transaction open in VisuaLeaf
One common cause of this error is a database tool holding a transaction open while your application tries to write. VisuaLeaf's SQL Editor makes an open transaction hard to miss.
- Switch the editor tab from Auto-commit to Manual commit when you want to check changes before keeping them.
- While statements are uncommitted, an UNCOMMITTED badge shows how many are waiting and for how long, and you are warned when a transaction has been idle long enough that it may be holding locks.
- Press Commit or Rollback before you go back to your application. Closing a tab with an open transaction asks first instead of leaving it open.
A long-running query can block writers too: press Stop, or Escape, to cancel it. See the SQL Editor.
What we found testing this
Two or three connections to one file, with one of them holding a lock. Rollback-journal mode is the SQLite default; WAL is the alternative.
- A busy timeout does not help when two transactions both read first, then write. Both connections ran
BEGIN, read a row, then wrote. Withtimeout=10the second writer still failed in 0.000 s, in both journal modes:
SQLite refuses to wait here because waiting would deadlock: each connection holds what the other needs. WithOperationalError: database is locked [SQLITE_BUSY] after 0.000sBEGIN IMMEDIATEon both, the second writer waited 1.09 s for the first to commit, then succeeded. That's why the quick answer uses it. - In the default journal mode, an unfinished read blocks commits. A connection that had read only the first row of a 1,000-row
SELECTmade another connection'scommit()fail. Reading the rest of the cursor released it. In WAL mode the same commit went through. - A missing
commit()in Python locks everyone else. Python's default mode opens a transaction before anINSERTand keeps it open until you commit:conn.in_transactionwasTrue, and a second connection's write failed until it was committed. - The defaults differ by client. The CLI failed in 5 ms with no waiting. Python and better-sqlite3 each waited about 5.2 s before raising, so an app can feel "slow, then broken" where the CLI is simply "broken".
Fix 1: wait for the lock instead of failing
Set a busy timeout on every connection. It's a per-connection setting, not stored in the file, so set it each time you open one:
PRAGMA busy_timeout = 5000;
import sqlite3
conn = sqlite3.connect("app.db", timeout=10) # seconds
const Database = require('better-sqlite3')
const db = new Database('app.db', { timeout: 10000 }) // milliseconds
sqlite3 -cmd ".timeout 5000" app.db
This fixes short collisions. It does nothing for the read-then-write pattern above, and it only hides a transaction that never ends.
Fix 2: switch to WAL mode
In the default rollback-journal mode, a reader and a committing writer block each other. In WAL mode, readers keep reading the last committed version while one writer works, so most "locked" errors on busy apps disappear:
PRAGMA journal_mode = WAL; -- returns "wal"; stays set for the file
WAL adds two files next to the database, app.db-wal and app.db-shm. Keep them with the database: copying only app.db while the app is running can lose recent writes. WAL also needs all connections on the same machine, so it doesn't work on network drives.
There is still only one writer at a time, even in WAL mode. If two processes write constantly, keep write transactions short or send writes through one process.
Fix 3: find what is holding the lock
- An uncommitted transaction in your own code. Look for writes without a
commit(), or an exception path that skips it. In Python,with conn:commits or rolls back for you. - A cursor that was never fully read. Fetch all rows, call
cursor.close(), or usefetchall()for small results. - A GUI or second tool with pending changes. A database browser holding edits it hasn't saved keeps a write lock. Commit or roll back there.
- Another process. On macOS and Linux,
lsof app.dblists the processes with the file open. - A network or synced folder. SQLite's locking relies on the file system. On NFS, SMB shares, Dropbox or OneDrive it can fail or misreport. Keep the database on a local disk.
Frequently Asked Questions
What is SQLITE_BUSY?
Result code 5. Another connection holds a lock this connection needs. It is reported as "database is locked" by the CLI, Python and Node drivers.
Why do I get "database is locked" even with a busy timeout?
Usually because two transactions started with plain BEGIN, both read, and then both tried to write. SQLite returns SQLITE_BUSY immediately to avoid a deadlock. Start write transactions with BEGIN IMMEDIATE.
Does WAL mode fix database is locked?
It fixes the reader-versus-writer cases, which are the most common. Two writers still take turns, so set a busy timeout as well.
What is the difference between "database is locked" and "database table is locked"?
"database is locked" (SQLITE_BUSY) is a conflict between connections. "database table is locked" (SQLITE_LOCKED) happens inside one connection, such as dropping a table while a query on it is still open.