Repository navigation
Description
Summary
Opening a database with experimental: ["multiprocess_wal"] fails when the -wal file is empty (0 bytes) but a leftover -tshm file still claims WAL frames:
failed to open database …: I/O error: short read on WAL frame at offset 3773952: expected 4096 bytes, got 0
The main SQLite file is intact (PRAGMA integrity_check = ok). Deleting -wal and -tshm lets Turso open it again. Stock sqlite3 also opens the main file because it ignores -tshm.
This is the same error class as #6454, but it is native @tursodatabase/database + multiprocess_wal, not wasm open/close.
Environment
@tursodatabase/database0.7.2- Bun 1.4.0 (also observed from our Effect layer using the same native package)
- Linux x86_64
Minimal reproduction
import { connect } from "@tursodatabase/database";
import { existsSync, statSync, truncateSync } from "node:fs";
const path = "./repro.db";
const wal = path + "-wal";
const tshm = path + "-tshm";
const db = await connect(path, { experimental: ["multiprocess_wal"] });
await db.exec("CREATE TABLE t (id INTEGER PRIMARY KEY, blob BLOB)");
const stmt = db.prepare("INSERT INTO t (blob) VALUES (?)");
const blob = Buffer.alloc(4096, 7);
for (let i = 0; i < 900; i++) {
await stmt.run(blob);
}
await db.close();
console.log({
db: statSync(path).size,
wal: existsSync(wal) ? statSync(wal).size : -1,
tshm: existsSync(tshm) ? statSync(tshm).size : -1,
});
// close() does not checkpoint: WAL stays large, -tshm magic is "TSHMWAL"
truncateSync(wal, 0);
await connect(path, { experimental: ["multiprocess_wal"] });Observed on this run:
- after close:
db2854912,wal3786312,tshm86016 (TSHMWAL\0) - after
truncateSync(wal, 0): reopen fails withshort read on WAL frame at offset 3773952: expected 4096 bytes, got 0
Offset 3773952 = 921 * 4096.
What we hit in the wild
A local multi-process runtime (auth / graphql / job worker sharing one file via multiprocess_wal) refused to open:
pf.db2281472 bytes (557 pages × 4096), SQLite 3.x, WAL journal mode, integrity okpf.db-wal0 bytespf.db-tshm86016 bytes, header magicTSHMWAL- error:
short read on WAL frame at offset 3345472: expected 4096 bytes, got 0(3345472 = 817 * 4096)
We do not know what truncated that WAL (process kill, checkpoint, or another opener creating an empty -wal over a leftover -tshm). The synthetic truncate above matches the failure exactly.
Expected
If -wal is empty or shorter than the -tshm frame index, treat that as “no WAL frames” (or discard stale -tshm) and open the checkpointed main file. Do not fail connect().
SQLite recovers from a missing/empty WAL; Turso’s multiprocess WAL index currently bricks open instead.
Workaround
Delete -wal and -tshm, then reopen. Uncheckpointed WAL data is already gone when -wal is 0 bytes; the main file is usable.
Activity
penberg commentedon Sep 22, 2026
@roboturso triage
roboturso commentedon Sep 22, 2026
@roboturso reproduced this issue at commit
ca8933a2e32b74edf6e24650c4f6ace9f0ad6f3c.Reproduce:
cargo test -p turso_core --lib multiprocess_empty_wal_stale_tshm_tests::multiprocess_open_recovers_when_wal_is_empty_but_tshm_claims_frames -- --exactReproducer: https://github.com/roboturso/turso/blob/issue-8536/REPRODUCER-8536.md
v5vsvkmwpv-debug commentedon Oct 25, 2026
We hit this exact failure in production and can report what triggers it — the issue says the cause of the truncation was unknown.
Trigger: OS crash / power-off. In our case a single power-off on 2026-10-18 20:25 left 9 databases in the store simultaneously in this state (
-wal0 bytes, leftover-tshm86016 bytes, magicTSHMWAL). All 9 failedconnect()with this error class; the offset varied per DB (e.g.366712,3773952).Still present in 0.8.3 — upgrading does not fix it.
Environment
@tursodatabase/database0.8.3 (latest)experimental: ["encryption", "multiprocess_wal"]Two additions to the workaround
The
-shmsidecar may need to go too. Your workaround says delete-waland-tshm. In our case a stale stock-sqlite3-shmwas also present and had to be moved as well — all three sidecars were quarantined together. Leaving-shmbehind left the DB still failing.Do not use the stock
sqlite3CLI to inspect a live Turso DB. Opening one withsqlite3recreates-shm, which breaks Turso's-tshmcorrespondence and turns a previously healthy DB into one that fails — with this error, or withCorrupt database: Invalid page type: 0depending on what the stale index ends up pointing at. This bit us during diagnosis: it made the blast radius look bigger than it was. Raw file inspection (stat/od) is safe; opening the DB is not.The file-level signature is not authoritative
We found DBs with the same "stale signature" (
-tshmpresent,-wal0 bytes) that Turso opened fine. The authoritative check is a driverconnect()attempt, not the file state.Scale matters when reproducing
A small WAL truncated to 0 with a leftover
-tshmmay open successfully (SQLite's checksum recovery silently drops the tail). We needed ~900 rows × 4 KiB (≈3.7 MiB WAL) for a deterministic failure — matching youroffset 3773952 = 921 × 4096observation.Self-healing tool
We built one and have been running it on a schedule since: it classifies every DB in the store via the real driver, quarantines only DBs that are provably stale and have an empty
-wal, re-verifies, and rolls the sidecars back if the re-open still fails. No data loss (row counts identical before/after).Source: https://github.com/v5vsvkmwpv-debug/opencode-config/blob/main/bin/turso-wal-check.sh
Happy to provide the repro script or more data if useful. Related: #6454, #8593.