{"record":{"id":"47b397885dba2018","repo":"benbjohnson/litestream","slug":"unsupported-page-size-d","errorCode":null,"errorMessage":"unsupported page size: %d","messagePattern":"unsupported page size: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":2794,"sourceCode":"\tpageSize := f.pageSize\n\tf.mu.Unlock()\n\tif pageSize == 0 {\n\t\tf.logger.Debug(\"page size not initialized\", \"pageSize\", 0)\n\t\treturn 0, &DBNotReadyError{Reason: \"page size not initialized\"}\n\t}\n\treturn pageSize, nil\n}\n\nfunc detectPageSizeFromInfos(ctx context.Context, client ReplicaClient, infos []*ltx.FileInfo) (uint32, error) {\n\tvar lastErr error\n\tfor i := len(infos) - 1; i >= 0; i-- {\n\t\tpageSize, err := readPageSizeFromInfo(ctx, client, infos[i])\n\t\tif err != nil {\n\t\t\tlastErr = err\n\t\t\tcontinue\n\t\t}\n\t\tif !isSupportedPageSize(pageSize) {\n\t\t\treturn 0, fmt.Errorf(\"unsupported page size: %d\", pageSize)\n\t\t}\n\t\treturn pageSize, nil\n\t}\n\tif lastErr != nil {\n\t\treturn 0, fmt.Errorf(\"read ltx header: %w\", lastErr)\n\t}\n\treturn 0, fmt.Errorf(\"no ltx file available to determine page size\")\n}\n\nfunc readPageSizeFromInfo(ctx context.Context, client ReplicaClient, info *ltx.FileInfo) (uint32, error) {\n\trc, err := client.OpenLTXFile(ctx, info.Level, info.MinTXID, info.MaxTXID, 0, ltx.HeaderSize)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"open ltx file: %w\", err)\n\t}\n\tdefer rc.Close()\n\tdec := ltx.NewDecoder(rc)\n\tif err := dec.DecodeHeader(); err != nil {\n\t\treturn 0, fmt.Errorf(\"decode ltx header: %w\", err)","sourceCodeStart":2776,"sourceCodeEnd":2812,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L2776-L2812","documentation":"When determining the SQLite page size from replica LTX headers, a header reported a page size that the VFS does not support (SQLite valid sizes are 512–65536 powers of two). The VFS refuses to proceed with an unusable page size.","triggerScenarios":"readPageSizeFromInfo returned a value failing isSupportedPageSize — typically a zero/garbage value from a truncated or corrupt LTX header, or a database created with an exotic page size.","commonSituations":"Corrupt or truncated first LTX file in the replica; files written by an incompatible litestream version; manually edited LTX data in storage.","solutions":["Inspect the first LTX file's header bytes to verify the page-size field","Re-replicate the database from the primary to replace corrupt LTX files","Run `litestream reset` to clear local state and rehydrate from the replica","Ensure the database uses a standard page size (PRAGMA page_size) such as 4096"],"exampleFix":"// before\nPRAGMA page_size=3000;  -- invalid for SQLite/litestream\n// after\nPRAGMA page_size=4096;  -- then re-replicate","handlingStrategy":"validation","validationCode":"func validPageSize(ps uint32) bool {\n    return ps >= 512 && ps <= 65536 && ps&(ps-1) == 0\n}\n// check on primary: PRAGMA page_size must pass validPageSize","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use a standard page size (e.g. 4096) on primary databases","Never hand-edit LTX files in storage","Verify replica integrity after storage migrations"],"tags":["page-size","ltx","corruption"],"backgroundTag":"invalid-config-value","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"}