Snapshot is out of date

Category: SnapshotVersions: 3.31.0+

🔴 Production Risk Error

Medium — snapshot-based reads must re-acquire a valid snapshot.

What this means

SQLITE_ERROR_SNAPSHOT (769) is returned by sqlite3_snapshot_open() when the requested historical snapshot is no longer available because the WAL has been checkpointed past that point.

Why it happens

1WAL checkpoint occurred after the snapshot was taken, invalidating it.
2Snapshot too old — WAL frames it references have been removed.

How to reproduce

sqlite3_snapshot_open() when the snapshot version is no longer in the WAL.

trigger — this will ERROR

# In C:
# sqlite3_snapshot *snap;
# sqlite3_snapshot_get(db, "main", &snap);
# ... WAL checkpoint happens ...
# sqlite3_snapshot_open(db, "main", snap) → SQLITE_ERROR_SNAPSHOT

SQLITE_ERROR_SNAPSHOT (769)

Fix 1

Why this works

Acquire a fresh snapshot: sqlite3_snapshot_get() after the checkpoint.

Fix 2

Why this works

Increase WAL autocheckpoint threshold to keep more history: PRAGMA wal_autocheckpoint=N

What not to do

✗

Why it's wrong:

Version notes

Sources

📚 Official docs: https://www.sqlite.org/rescode.html#error_snapshot

🔧 Source ref: sqlite3.h — SQLITE_ERROR_SNAPSHOT = 769

📖 Further reading: sqlite3_snapshot_open()

Confidence assessment

⚠️ MEDIUM confidence

Stable.