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.

```text
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:

```bash
lsof /path/to/app.db
```

   Close what you do not need.

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

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

   Expected output: `wal`.

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

```sql
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.