# sqlite3.OperationalError: database is locked
  (background: SQLite busy timeout of 5000ms exceeded)

- **ID:** `database/sqlite-busy-timeout-exceeded`
- **Domain:** database
- **Category:** runtime_error
- **Verification:** ai_generated
- **Fix Rate:** 85%

## Root Cause

A write transaction is held by another connection for longer than the busy timeout, causing concurrent writes to fail.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| SQLite 3.40 | active | — | — |
| SQLite 3.41 | active | — | — |
| SQLite 3.42 | active | — | — |

## Workarounds

1. **Set a higher busy timeout: PRAGMA busy_timeout = 30000; (30 seconds) to allow longer waits for locks.** (90% success)
   ```
   Set a higher busy timeout: PRAGMA busy_timeout = 30000; (30 seconds) to allow longer waits for locks.
   ```
2. **Switch to WAL mode: PRAGMA journal_mode=WAL; This allows concurrent reads while a write is in progress.** (85% success)
   ```
   Switch to WAL mode: PRAGMA journal_mode=WAL; This allows concurrent reads while a write is in progress.
   ```
3. **Use a connection pool with retry logic: from sqlite3 import connect; import time; for i in range(5): try: conn.execute(...); break; except sqlite3.OperationalError: time.sleep(1)** (80% success)
   ```
   Use a connection pool with retry logic: from sqlite3 import connect; import time; for i in range(5): try: conn.execute(...); break; except sqlite3.OperationalError: time.sleep(1)
   ```

## Dead Ends

- **Set PRAGMA busy_timeout to 0 to disable timeout** — Disabling timeout causes immediate failure on lock contention, making the problem worse instead of better. (80% fail)
- **Use WAL mode but keep journal_mode=DELETE** — WAL mode improves concurrency for readers but does not eliminate write contention; the lock still exists. (50% fail)