{"record":{"id":"9bd48f3a505c5a11","repo":"benbjohnson/litestream","slug":"create-page-cache-w","errorCode":null,"errorMessage":"create page cache: %w","messagePattern":"create page cache: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":1134,"sourceCode":"\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}\n\t}\n\tf.pos = pos\n\n\t// Initialize write support TXID tracking\n\tif f.writeEnabled {\n\t\tf.expectedTXID = pos.TXID\n\t\tf.pendingTXID = pos.TXID + 1\n\t\tf.logger.Debug(\"write support enabled\", \"expectedTXID\", f.expectedTXID, \"pendingTXID\", f.pendingTXID)\n\n\t\t// Initialize write buffer file for durability (discards any existing buffer)\n\t\tif err := f.initWriteBuffer(); err != nil {","sourceCodeStart":1116,"sourceCodeEnd":1152,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L1116-L1152","documentation":"Raised during VFSFile.Open when constructing the LRU page cache fails. lru.New essentially only fails when the entry capacity is invalid (<= 0), meaning CacheSize was misconfigured relative to the detected page size. Open aborts since reads depend on the cache.","triggerScenarios":"lru.New[uint32, []byte](cacheEntries) returns an error — practically only when cacheEntries computed from f.CacheSize / pageSize is zero or negative and the guard was bypassed, e.g. integer overflow with a huge CacheSize or pageSize of 0 from a bad detection.","commonSituations":"CacheSize config set to 0 or a negative/huge value; a corrupt LTX header reporting a bogus page size making the division overflow.","solutions":["Set CacheSize in the VFS config to a sane positive value (e.g. >= a few MB)","Verify the detected page size is sane by checking the replica's LTX header","Ensure pageSize is not 0 before dividing (guard in config loading)","Update litestream if the LTX header layout seems incompatible"],"exampleFix":"// before\nf.CacheSize = 0 // misconfig\ncacheEntries := f.CacheSize / int(pageSize) // 0 -> lru.New error\n// after\nf.CacheSize = 16 * 1024 * 1024 // at least several pages\nif f.CacheSize < int(pageSize) { f.CacheSize = int(pageSize) }","handlingStrategy":"validation","validationCode":"if cfg.CacheSize <= 0 { return errors.New(\"CacheSize must be a positive byte value\") }","typeGuard":"func cacheSizeValid(n int) bool { return n > 0 && n < math.MaxInt32 }","tryCatchPattern":"if err := file.Open(ctx); err != nil {\n    if strings.Contains(err.Error(), \"create page cache\") {\n        return fmt.Errorf(\"bad CacheSize config: %w\", err)\n    }\n    return err\n}","preventionTips":["Always configure a positive CacheSize at least one page in size","Watch for unit mix-ups (bytes vs MB) in config files","Sanity-check detected page size when loading replica metadata"],"tags":["lru","cache","configuration"],"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"}