SQLite
sqlite3.OperationalError: database is locked
SQLite database is locked (SQLITE_BUSY) means another connection is writing. Causes, busy_timeout, WAL mode, and how to fix it for good.
What it means
SQLite only allows one writer at a time to a given database file. SQLITE_BUSY — the database is locked message in most drivers — is what a connection gets back when it can’t get the lock it needs in time: usually a write while another connection (often in a different process) is in the middle of one. In the default rollback-journal mode, readers and writers also block each other briefly: a writer can’t commit while readers are active, and new readers wait while a writer commits. It’s not data corruption and it’s not a permissions problem; it’s SQLite correctly refusing to let two writes collide.
Common causes
- A concurrent write from another process or thread — the single most common cause, especially with a web server running multiple worker processes against the same SQLite file, or a script and an interactive session open at the same time.
- A long-running transaction that hasn’t committed or rolled back, holding the write lock far longer than the actual work requires.
- No
busy_timeoutset, so instead of waiting briefly for the other writer to finish, the connection fails immediately on the first collision. - Journal mode left at the default (rollback journal) under real concurrency, where readers and a writer block each other more than they would under WAL.
- A network filesystem (NFS, some cloud-synced folders) under the database file, where SQLite’s locking primitives don’t behave the same as on a local disk and can report
SQLITE_BUSYmore often, or hold locks longer than expected.
How to fix it
- Set a busy timeout so a connection retries for a while before giving up, instead of failing on the first collision:
PRAGMA busy_timeout = 5000;(5 seconds), or the equivalentsqlite3_busy_timeout()call / driver option. - Switch to WAL mode, which lets readers proceed without blocking on a writer:
PRAGMA journal_mode = WAL;(set once per database file; it persists). WAL needs all connections on the same machine — it doesn’t work over a network filesystem. - Keep write transactions short — commit as soon as the write is done rather than holding a transaction open across unrelated work.
- If a specific write needs a guarantee it won’t hit
SQLITE_BUSYmid-transaction, start it withBEGIN IMMEDIATErather than a plainBEGIN, so the busy failure (if any) happens up front instead of partway through. - Avoid putting the database file on a network filesystem if concurrent access from multiple processes is expected; SQLite’s file-locking guarantees are documented for local filesystems.
- If the lock persists with no process obviously writing, find what still has the file open (
lsof data.dbon macOS/Linux, Resource Monitor on Windows) — a forgotten shell, a background job, a sync tool. Don’t delete the-journalor-walfile next to the database: they hold the data SQLite needs to roll back or finish transactions, and removing them can corrupt the database.
In Tablyne
If you only need to look at the data, mark the connection read-only: Tablyne then opens the file with SQLITE_OPEN_READONLY, not just a UI toggle, so it never takes a write lock and can’t be the connection that blocks your application’s writes.
Look without getting in the way. Download Tablyne or open the SQLite Browser.
Sources
Frequently asked questions
Is 'database is locked' the same as SQLITE_BUSY? +
Yes — the driver-level message (sqlite3.OperationalError: database is locked in Python, similar wording in other languages) is how SQLITE_BUSY surfaces at the application level.
Does closing my program guarantee the lock is released? +
Yes. SQLite's locks belong to the open connection, so the operating system releases them when the process exits, even after a crash. If the error persists, some other process still has the database open (a second app, a background job, a file-sync tool). Never delete a leftover -journal or -wal file to 'unlock' it: the rollback journal is what undoes a half-finished write and the WAL file holds committed transactions, so deleting either can corrupt the database or lose data. Opening the database normally lets SQLite recover them.
Will switching to WAL mode remove the error completely? +
It removes most of it, since WAL lets one writer and many readers proceed at once instead of blocking each other. It doesn't remove the writer-vs-writer case: two connections both trying to write at the same instant will still have one of them wait or fail if the timeout is too short.