{"record":{"id":"e8b712600f671203","repo":"benbjohnson/litestream","slug":"invalid-replica-checksum-mismatch","errorCode":null,"errorMessage":"invalid replica, checksum mismatch","messagePattern":"invalid replica, checksum mismatch","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"litestream.go","lineNumber":34,"sourceCode":")\n\n// Naming constants.\nconst (\n\tMetaDirSuffix = \"-litestream\"\n)\n\n// SQLite checkpoint modes.\nconst (\n\tCheckpointModePassive  = \"PASSIVE\"\n\tCheckpointModeFull     = \"FULL\"\n\tCheckpointModeRestart  = \"RESTART\"\n\tCheckpointModeTruncate = \"TRUNCATE\"\n)\n\n// Litestream errors.\nvar (\n\tErrNoSnapshots      = errors.New(\"no snapshots available\")\n\tErrChecksumMismatch = errors.New(\"invalid replica, checksum mismatch\")\n\tErrLTXCorrupted     = errors.New(\"ltx file corrupted\")\n\tErrLTXMissing       = errors.New(\"ltx file missing\")\n\tErrDiskFull         = errors.New(\"disk full\")\n)\n\n// LTXError provides detailed context for LTX file errors with recovery hints.\ntype LTXError struct {\n\tOp      string // Operation that failed (e.g., \"open\", \"read\", \"validate\")\n\tPath    string // File path\n\tLevel   int    // LTX level (0 = L0, etc.)\n\tMinTXID uint64 // Minimum transaction ID\n\tMaxTXID uint64 // Maximum transaction ID\n\tErr     error  // Underlying error\n\tHint    string // Recovery hint for users\n}\n\nfunc (e *LTXError) Error() string {\n\tif e.Path != \"\" {","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/litestream.go#L16-L52","documentation":"ErrChecksumMismatch indicates a replica LTX file's contents do not match its recorded checksum, so the replicated data cannot be trusted. It is wrapped in LTXError and marked auto-recoverable: with the auto-recover replica option enabled, litestream resets local state and re-syncs from the replica.","triggerScenarios":"Decoded LTX data failing checksum verification during verify/apply operations; surfacing through NewLTXError and LTXError.IsAutoRecoverable (litestream.go:68) which returns true for it.","commonSituations":"Bit rot or truncated uploads in object storage, corrupted local .sqlite-litestream cache files, partial network reads persisted to disk, storage provider bugs.","solutions":["Run `litestream reset <db>` to clear corrupted local LTX state and re-sync from the replica","Enable auto-recover: true on the replica so this resets automatically","Delete the .sqlite-litestream directory and restart if reset is unavailable","Investigate the storage backend for truncated or corrupted uploads"],"exampleFix":"# before (yaml)\nreplicas:\n  - url: s3://bucket/db\n# after\nreplicas:\n  - url: s3://bucket/db\n    auto-recover: true","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isAutoRecoverableLTX(err error) bool {\n    var le *litestream.LTXError\n    return errors.As(err, &le) && le.IsAutoRecoverable()\n}","tryCatchPattern":"if err := db.Sync(ctx); err != nil {\n    var ltxErr *litestream.LTXError\n    if errors.As(err, &ltxErr) && errors.Is(ltxErr.Err, litestream.ErrChecksumMismatch) {\n        // reset local state and re-sync from replica\n        return litestream.Reset(ctx, dbPath)\n    }\n    return err\n}","preventionTips":["Enable auto-recover: true on replicas","Monitor storage for truncated uploads","Keep disk headroom to avoid partial writes","Verify backups periodically with `litestream ltx`"],"tags":["checksum","corruption","ltx","replica","recovery"],"backgroundTag":"checksum-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"}