{"record":{"id":"f1a8bf03c60ad69d","repo":"benbjohnson/litestream","slug":"detect-page-size-w","errorCode":null,"errorMessage":"detect page size: %w","messagePattern":"detect page size: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":1123,"sourceCode":"func (f *VFSFile) Open() error {\n\tf.logger.Debug(\"opening file\")\n\n\t// Try to get restore plan. For write-enabled VFS, we can create a new database\n\t// if no LTX files exist yet.\n\tinfos, err := f.waitForRestorePlan()\n\tif err != nil {\n\t\t// If write mode is enabled and no files exist, we can create a new database\n\t\tif f.writeEnabled && errors.Is(err, ErrTxNotAvailable) {\n\t\t\tf.logger.Info(\"no existing database found, creating new database\")\n\t\t\treturn f.openNewDatabase()\n\t\t}\n\t\treturn err\n\t}\n\n\tpageSize, err := detectPageSizeFromInfos(f.ctx, f.client, infos)\n\tif err != nil {\n\t\tf.logger.Error(\"cannot detect page size\", \"error\", err)\n\t\treturn fmt.Errorf(\"detect page size: %w\", err)\n\t}\n\tf.pageSize = pageSize\n\n\t// Initialize page cache. Convert byte size to number of pages.\n\tcacheEntries := f.CacheSize / int(pageSize)\n\tif cacheEntries < 1 {\n\t\tcacheEntries = 1\n\t}\n\tcache, err := lru.New[uint32, []byte](cacheEntries)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"create page cache: %w\", err)\n\t}\n\tf.cache = cache\n\n\t// Determine the current position based off the latest LTX file.\n\tvar pos ltx.Pos\n\tif len(infos) > 0 {\n\t\tpos = ltx.Pos{TXID: infos[len(infos)-1].MaxTXID}","sourceCodeStart":1105,"sourceCodeEnd":1141,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L1105-L1141","documentation":"Raised during VFSFile.Open when the page size could not be determined from the replica's LTX file infos. detectPageSizeFromInfos inspects the latest LTX file (header or index) to learn the database page size, which is required before the page cache and index can be built. A failure here aborts opening the database-backed VFS file.","triggerScenarios":"Opening a VFS file whose replica has unreadable/corrupt LTX infos: the latest LTX header is truncated, the file was written by an incompatible version, or reading from the replica client fails (network/permission error).","commonSituations":"Corrupted or partially-uploaded LTX files in the replica bucket; replica storage backend returning errors; opening a replica written by an older litestream with unexpected header layout.","solutions":["Verify the replica's LTX files are intact (litestream ltx -level all) and re-replicate from the primary if corrupt","Check replica client connectivity/credentials so LTX files can be read","Confirm both litestream versions are compatible; upgrade the reader to match the writer","Run litestream reset for the database if local LTX state is corrupted"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"infos, err := client.LTXInfos(ctx); if len(infos) == 0 || err != nil { /* fix replica before opening */ }","typeGuard":"func replicaReadable(c vfs.ReplicaClient) bool { _, err := c.LTXInfos(context.Background()); return err == nil }","tryCatchPattern":"if err := file.Open(ctx); err != nil {\n    if strings.Contains(err.Error(), \"detect page size\") {\n        return fmt.Errorf(\"replica LTX unreadable/corrupt: %w\", err)\n    }\n    return err\n}","preventionTips":["Verify replica integrity with litestream ltx before opening","Keep writer and reader litestream versions compatible","Ensure storage credentials/permissions allow reading LTX files"],"tags":["page-size","ltx","open","replica"],"backgroundTag":"database-query-failed","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"}