{"record":{"id":"13289687cb85d2fb","repo":"benbjohnson/litestream","slug":"page-size-mismatch-got-d-expected-d","errorCode":null,"errorMessage":"page size mismatch: got %d, expected %d","messagePattern":"page size mismatch: got (.+?), expected (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"vfs.go","lineNumber":1717,"sourceCode":"\tif data, ok := f.cache.Get(pgno); ok {\n\t\tcopy(buf, data)\n\t\treturn nil\n\t}\n\n\t// Get page index element\n\telem, ok := f.index[pgno]\n\tif !ok {\n\t\treturn fmt.Errorf(\"page not found: %d\", pgno)\n\t}\n\n\t// Fetch from remote\n\t_, data, err := FetchPage(f.ctx, f.client, elem.Level, elem.MinTXID, elem.MaxTXID, elem.Offset, elem.Size)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tif uint32(len(data)) != pageSize {\n\t\treturn fmt.Errorf(\"page size mismatch: got %d, expected %d\", len(data), pageSize)\n\t}\n\n\tcopy(buf, data)\n\tf.cache.Add(pgno, data)\n\treturn nil\n}\n\nfunc (f *VFSFile) Truncate(size int64) error {\n\tf.logger.Debug(\"truncating file\", \"size\", size)\n\n\tpageSize, err := f.pageSizeBytes()\n\tif err != nil {\n\t\treturn err\n\t}\n\n\tnewCommit := uint32(size / int64(pageSize))\n\n\tf.mu.Lock()","sourceCodeStart":1699,"sourceCodeEnd":1735,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L1699-L1735","documentation":"FetchPage returned a page whose byte length differs from the VFS file's configured page size (f.pageSizeBytes / len(buf)). Litestream assumes every LTX page image matches the database page size; a mismatch means the replica data and the local page size disagree, so copying it would corrupt the page buffer.","triggerScenarios":"Calling WriteAt (read-modify-write path) on a page present in f.index but whose stored LTX record was written with a different page size — e.g. the remote snapshot was created from a database with a different page_size, or a truncated/corrupt LTX record yields a short read.","commonSituations":"Pointing a VFS at a replica from a different database with a different PRAGMA page_size; restoring across litestream versions where page-size handling changed; corrupted or truncated LTX files on storage (partial upload); manually copied replica data between databases.","solutions":["Verify the remote database snapshot's page size matches the local VFS database page size; do not share replicas across differently-configured databases.","Inspect the LTX file at the indexed offset (litestream ltx -level 0) for truncation/corruption.","Re-replicate: run litestream reset for the database so a fresh snapshot with the correct page size is created.","Check for interrupted uploads/partial writes at the storage backend and re-upload affected LTX files.","Ensure the client app doesn't change PRAGMA page_size on an existing replicated database."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Verify snapshot page size matches local DB before pointing VFS at a replica:\n// read bytes 16-17 of the DB header (page size) and compare with remote snapshot config.\nlocalPS := binary.BigEndian.Uint16(header[16:18]) // must equal replica page size","typeGuard":"func pageSizeOK(data []byte, want uint32) bool { return uint32(len(data)) == want }","tryCatchPattern":"if err := readPageForWrite(pgno, buf); err != nil {\n    if strings.Contains(err.Error(), \"page size mismatch\") {\n        // stop writes; re-replicate with matching page size\n    }\n}","preventionTips":["Never change PRAGMA page_size on a database that is already replicated.","Do not reuse a replica bucket across databases with different page sizes.","Validate LTX integrity after uploads (checksums) to catch truncation.","Run litestream ltx to inspect remote page records after any restore."],"tags":["go","sqlite-vfs","page-size","corruption","ltx"],"backgroundTag":"tensor-shape-mismatch","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"}