SQLITE_BUSY_SNAPSHOTWARNINGTier 2 — Caution⚠️ MEDIUM confidenceBusy: WAL snapshot is out of date
🔴 Production Risk Error
Medium — write transactions will be blocked until the read transaction ends.
What this means
SQLITE_BUSY_SNAPSHOT (517) is returned in WAL mode when a read transaction sees an older snapshot and a write transaction cannot proceed because a checkpoint would need to overwrite pages that the read transaction is viewing.
Why it happens
- 1Long-running read transaction in WAL mode is blocking the checkpoint.
- 2Read connection holds a snapshot that is older than the write connection needs.
How to reproduce
WAL-mode database with concurrent long-running readers and active writers.
-- Connection A (read transaction, holds old snapshot):
BEGIN; SELECT * FROM big_table;
-- Connection B (write transaction, blocked):
-- BEGIN; INSERT INTO big_table ... → SQLITE_BUSY_SNAPSHOTFix 1
Why this works
Shorten read transactions — commit or rollback reads as soon as possible.
Fix 2
Why this works
Use BEGIN IMMEDIATE on writers to detect contention early.
Fix 3
Why this works
Tune WAL checkpoint threshold: PRAGMA wal_autocheckpoint=N
What not to do
Why it's wrong:
Sources
📚 Official docs: https://www.sqlite.org/rescode.html#busy_snapshot
🔧 Source ref: sqlite3.h — SQLITE_BUSY_SNAPSHOT = 517
📖 Further reading: WAL mode
Confidence assessment
⚠️ MEDIUM confidence
Stable.
See also
🔗 Related errors
📄 Reference pages