{"record":{"id":"5758297c313ea735","repo":"benbjohnson/litestream","slug":"no-ltx-file-available-to-determine-page-size","errorCode":null,"errorMessage":"no ltx file available to determine page size","messagePattern":"no ltx file available to determine page size","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":2801,"sourceCode":"}\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)\n\t}\n\treturn dec.Header().PageSize, nil\n}\n\nfunc isSupportedPageSize(pageSize uint32) bool {\n\tswitch pageSize {\n\tcase 512, 1024, 2048, 4096, 8192, 16384, 32768, 65536:","sourceCodeStart":2783,"sourceCodeEnd":2819,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L2783-L2819","documentation":"Litestream's VFS page-size detection reads the header of the newest LTX file in the replica to learn the database's page size. When the replica contains no LTX files at all (the file listing comes back empty), it cannot determine a page size and returns this error. It indicates the remote has no backup data to read from, not a malformed file.","triggerScenarios":"Calling restore/VFS open against a replica whose CalcRestorePlan yields zero files — e.g. a freshly configured replica that has never had a successful sync, or after all LTX files were pruned/deleted from storage.","commonSituations":"Pointing a VFS client at a brand-new bucket/prefix before the first litestream sync ran; wrong replica path so the listing finds nothing; retention/lifecycle rules deleted all objects; using `litestream reset` on a replica with no prior snapshots.","solutions":["Verify the replica actually has LTX objects (litestream ltx -level all or list the bucket prefix)","Run a litestream replicate sync to populate the remote before opening via VFS","Check the config: correct bucket, path/prefix and database path — a wrong prefix lists zero files","If local LTX state is corrupted, use litestream reset and re-replicate"],"exampleFix":"// before: opening VFS against an empty replica prefix\nclient, _ := litestreamvfs.Open(ctx, \"s3://my-bucket/wrong-prefix/db\")\n// after: point at the prefix the replicator writes to and confirm files exist\nclient, _ := litestreamvfs.Open(ctx, \"s3://my-bucket/litestream/db\")","handlingStrategy":"validation","validationCode":"infos, err := client.ListLTXFiles(ctx)\nif err != nil { return err }\nif len(infos) == 0 { return fmt.Errorf(\"replica has no ltx files; run replicate first\") }","typeGuard":null,"tryCatchPattern":"if err := openVFS(ctx); err != nil {\n    if strings.Contains(err.Error(), \"no ltx file available\") {\n        return syncReplicaFirst(ctx)\n    }\n    return err\n}","preventionTips":["Run a successful replicate sync before any VFS/restore open","Verify bucket prefix matches the replicator's path","Audit storage lifecycle rules so retention cannot delete all LTX files"],"tags":["vfs","ltx","page-size","replica"],"backgroundTag":"empty-result-set","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"}