{"record":{"id":"4d9e6455c1f6fb2d","repo":"benbjohnson/litestream","slug":"encode-ltx-frame-pgno-d-w","errorCode":null,"errorMessage":"encode ltx frame (pgno=%d): %w","messagePattern":"encode ltx frame \\(pgno=(.+?)\\): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":2315,"sourceCode":"\t\t// Check if the caller has canceled during processing.\n\t\tselect {\n\t\tcase <-ctx.Done():\n\t\t\treturn context.Cause(ctx)\n\t\tdefault:\n\t\t}\n\n\t\t// If page exists in the WAL, read from there.\n\t\tif offset, ok := pageMap[pgno]; ok {\n\t\t\tdb.Logger.Log(ctx, internal.LevelTrace, \"encode page from wal\", \"txid\", enc.Header().MinTXID, \"offset\", offset, \"pgno\", pgno, \"type\", \"db+wal\")\n\n\t\t\tif n, err := walFile.ReadAt(data, offset+WALFrameHeaderSize); err != nil {\n\t\t\t\treturn fmt.Errorf(\"read page %d @ %d: %w\", pgno, offset, err)\n\t\t\t} else if n != len(data) {\n\t\t\t\treturn fmt.Errorf(\"short read page %d @ %d\", pgno, offset)\n\t\t\t}\n\n\t\t\tif err := enc.EncodePage(ltx.PageHeader{Pgno: pgno}, data); err != nil {\n\t\t\t\treturn fmt.Errorf(\"encode ltx frame (pgno=%d): %w\", pgno, err)\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\n\t\toffset := int64(pgno-1) * int64(db.pageSize)\n\t\tdb.Logger.Log(ctx, internal.LevelTrace, \"encode page from database\", \"offset\", offset, \"pgno\", pgno)\n\n\t\t// Otherwise read directly from the database file.\n\t\tif _, err := db.f.ReadAt(data, offset); err != nil {\n\t\t\treturn fmt.Errorf(\"read database page %d: %w\", pgno, err)\n\t\t}\n\t\tif err := enc.EncodePage(ltx.PageHeader{Pgno: pgno}, data); err != nil {\n\t\t\treturn fmt.Errorf(\"encode ltx frame (pgno=%d): %w\", pgno, err)\n\t\t}\n\t}\n\n\treturn nil\n}","sourceCodeStart":2297,"sourceCodeEnd":2333,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L2297-L2333","documentation":"The LTX encoder rejected a page encode during the DB+WAL snapshot write. Litestream wraps the encoder error as 'encode ltx frame (pgno=%d):' identifying the offending page. The ltx library enforces invariants such as strictly increasing page numbers and valid page sizes, so this almost always indicates corrupted internal state rather than caller error.","triggerScenarios":"enc.EncodePage(ltx.PageHeader{Pgno: pgno}, data) at db.go:2314/2327 failed: pages emitted out of pgno order, a bad pageSize configured on the encoder (must match the SQLite page size), encoder closed or in an invalid state, or header/page mismatch after partial writes.","commonSituations":"Mismatched page size between the database file and litestream configuration after the DB was recreated with a different page_size; interrupted prior sync leaving an encoder in a bad state; bugs from manually editing/copying LTX state; ltx library version incompatibility with existing LTX files.","solutions":["Verify the configured page size matches the actual SQLite page size (`PRAGMA page_size;`).","Run `litestream reset` for the database to clear local LTX state and start a fresh snapshot.","Upgrade litestream and the ltx library to matching versions; LTX files are immutable so old incompatible state must be reset.","If reproducible, capture the pgno and report with the full error chain, since out-of-order pages indicate internal state corruption."],"exampleFix":"// before\n# db recreated with page_size=8192 but config assumes 4096\n# litestream.yml\n# (no page size handling) -> encode errors on snapshot\n// after\nsqlite3 db \"PRAGMA page_size;\"   # confirm actual size\nlitestream reset /path/to/db      # clear stale LTX state","handlingStrategy":"validation","validationCode":"const pageSize = db.pragma('page_size') // confirm matches litestream's expected size\nif (pageSize !== expectedPageSize) throw new Error('page size mismatch; reset litestream state')","typeGuard":null,"tryCatchPattern":"if err := db.Sync(ctx); err != nil {\n\tif strings.Contains(err.Error(), \"encode ltx frame\") {\n\t\t// capture pgno from message; reset LTX state\n\t}\n\treturn err\n}","preventionTips":["Keep the SQLite page size stable; if it changes, run `litestream reset`.","Pin litestream/ltx versions; upgrade together.","Never hand-edit or mix LTX files from different versions.","On persistent encode failures, rebuild state from a clean snapshot."],"tags":["ltx","encoder","page-size","snapshot"],"backgroundTag":"internal-invariant-violation","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}