SQLite MCP: database is locked (another process holds the write lock)

TL;DR: database is locked means another program has your SQLite file open for writing. Close the other connection, or enable WAL mode and set a busy timeout so the MCP server waits its turn instead of failing.

Error: database is locked

Fix it

1. Find the competing process. Usual suspects: a GUI database browser, a second MCP client, a dev server, or a hung earlier server process:

lsof /path/to/app.db

Close what you do not need.

1. If concurrent access is legitimate, enable WAL mode. WAL lets readers proceed while a writer works:

sqlite3 /path/to/app.db "PRAGMA journal_mode=WAL;"

Expected output: wal.

1. Ask the server to wait instead of failing instantly. If your server supports init SQL or pragmas, set a busy timeout (milliseconds):

PRAGMA busy_timeout = 5000;

Restart the MCP client after config changes.

Expected: writes that previously failed now succeed after a short wait.

When to use this

• Writes through the MCP server fail intermittently with database is locked.
• Reads work fine. Only writes fail.

When NOT to use this

• Reads also fail. That is a path or corruption problem, not locking.
• The error is unable to open database file. Different problem.

Compatibility

• @modelcontextprotocol/server-sqlite and any SQLite-backed MCP server.
• SQLite 3.x.

Why it happens

SQLite is a single-file database with coarse locking: one writer at a time, and in the default rollback-journal mode a writer blocks readers too. MCP servers hold connections open for the client session, so a second tool (or your own sqlite3 shell) that starts a write transaction locks everyone else out until it commits.

Edge cases

• WAL mode creates -wal and -shm sidecar files. All three must stay together; do not copy just the .db file.
• A crashed process can leave a stale lock. If no process shows in lsof but the lock persists, the -journal file may be orphaned. Back up, then remove the journal file.
• Network filesystems (NFS, some cloud-synced folders) have unreliable locking. Keep SQLite files on local disk.