{"record":{"id":"a089a91d1a74941c","repo":"benbjohnson/litestream","slug":"unsupported-wal-version-d","errorCode":null,"errorMessage":"unsupported wal version: %d","messagePattern":"unsupported wal version: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"wal_reader.go","lineNumber":123,"sourceCode":"\tcase 0x377f0682:\n\t\tr.bo = binary.LittleEndian\n\tcase 0x377f0683:\n\t\tr.bo = binary.BigEndian\n\tdefault:\n\t\treturn fmt.Errorf(\"invalid wal header magic: %x\", magic)\n\t}\n\n\t// If the header checksum doesn't match then we may have failed with\n\t// a partial WAL header write during checkpointing.\n\tchksum1 := binary.BigEndian.Uint32(hdr[24:])\n\tchksum2 := binary.BigEndian.Uint32(hdr[28:])\n\tif v0, v1 := WALChecksum(r.bo, 0, 0, hdr[:24]); v0 != chksum1 || v1 != chksum2 {\n\t\treturn io.EOF\n\t}\n\n\t// Verify version is correct.\n\tif version := binary.BigEndian.Uint32(hdr[4:]); version != 3007000 {\n\t\treturn fmt.Errorf(\"unsupported wal version: %d\", version)\n\t}\n\n\tr.pageSize = binary.BigEndian.Uint32(hdr[8:])\n\tr.seq = binary.BigEndian.Uint32(hdr[12:])\n\tr.salt1 = binary.BigEndian.Uint32(hdr[16:])\n\tr.salt2 = binary.BigEndian.Uint32(hdr[20:])\n\tr.chksum1, r.chksum2 = chksum1, chksum2\n\n\treturn nil\n}\n\n// ReadFrame reads the next frame from the WAL and returns the page number.\n// Returns io.EOF at the end of the valid WAL.\nfunc (r *WALReader) ReadFrame(ctx context.Context, data []byte) (pgno, commit uint32, err error) {\n\treturn r.readFrame(ctx, data, true)\n}\n\nfunc (r *WALReader) readFrame(ctx context.Context, data []byte, verifyChecksum bool) (pgno, commit uint32, err error) {","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/wal_reader.go#L105-L141","documentation":"SQLite embeds a format version (3007000, i.e. SQLite 3.7.0) at bytes 4-8 of the WAL header. Litestream rejects WAL files written with any other version, as their frame format cannot be assumed compatible. Note this check only runs after the header checksum passes, so the version field is trusted.","triggerScenarios":"Reading a WAL file whose version field is not exactly 3007000 — practically only possible with a future/hypothetical SQLite WAL format change, a manually crafted file, or corruption that happens to pass the checksum.","commonSituations":"Extremely rare; mostly seen when a non-SQLite tool wrote the file or a hand-built SQLite fork changed the WAL format; could also appear when pointing Litestream at an unrelated file that coincidentally has valid magic and checksum.","solutions":["Verify the SQLite version writing the WAL — standard releases use version 3007000 and should never trigger this","Hexdump the header (xxd -l 32 file) and inspect bytes 4-8 for the expected 00 2d e2 18 (3007000)","If a custom SQLite build is in use, rebuild against stock SQLite","Restore from replica and re-replicate if the WAL is corrupt"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"hdr := make([]byte, 8)\nio.ReadFull(f, hdr)\nif binary.BigEndian.Uint32(hdr[4:]) != 3007000 {\n    return fmt.Errorf(\"unsupported WAL version %d; need stock SQLite WAL format\", binary.BigEndian.Uint32(hdr[4:]))\n}","typeGuard":null,"tryCatchPattern":"r, err := NewWALReader(ctx, f, logger)\nif err != nil && strings.Contains(err.Error(), \"unsupported wal version\") {\n    return fmt.Errorf(\"WAL written by non-standard SQLite build: %w\", err)\n}","preventionTips":["Use official SQLite releases (or modernc.org/sqlite) — stock WALs are always version 3007000","Never point the reader at hand-crafted or tool-generated files","Rebuild any custom SQLite fork against the standard WAL format","Treat this error as a signal of file corruption or wrong-file-type, not a runtime condition"],"tags":["sqlite","wal","version","compatibility"],"backgroundTag":"unsupported-operation","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}