SQLite database is locked: find the blocker
When SQLite reports a lock error, look for another connection or an unfinished transaction holding the access you need. Save the exact error first. Increasing a timeout or deleting a companion file won’t tell you what caused it.
Keep the exact error code
SQLITE_BUSY and SQLITE_LOCKED are not identical. BUSY often involves another connection; LOCKED can involve conflicts within a connection or shared-cache use. Copy the full message and the extended error code if your client shows it. SQLite's result-code reference describes the distinctions.
Check your own open work first
- Look for a transaction you started in this editor or another tab.
- Review pending changes before deciding to commit or roll back.
- Finish the transaction deliberately; do not close a window and assume the desired data was saved.
- Retry the original operation once and record whether the result changed.
Next, check whether the application's background job, another GUI, a shell session or a test process is using the same file. Coordinate with the owner rather than killing an unfamiliar process. When you only need to inspect data, an application-supported backup or consistent snapshot can separate that task from a live writer.
Understand what a timeout can and cannot do
A busy timeout can wait for some temporary contention to clear. It does not fix a transaction that never ends, guarantee every lock will wait, or turn SQLite into a many-writer database. Check your driver's behavior before adding retry loops. Repeating a write after an uncertain outcome also requires knowing whether the first attempt committed.
Do not delete WAL or journal files
They can be part of SQLite's recovery state. In WAL mode, readers and a writer can overlap in many situations, but there is still one writer at a time. SQLite's WAL documentation explains the concurrency and checkpoint constraints. Changing journal mode is a database configuration decision, not a harmless repair button.
When reporting a persistent problem, include whether the file is local or on shared storage, which programs use it, the operation that fails and the transaction state. Keep a recoverable snapshot before trying a configuration change on a disposable copy.
Continue reading
WAL and companion files · Create a consistent backup
For the desktop workflow, compare plainDB features on Mac and Windows or download the 14-day trial.