{"record":{"id":"0e219ee09ec43480","repo":"benbjohnson/litestream","slug":"ltx-file-corrupted","errorCode":null,"errorMessage":"ltx file corrupted","messagePattern":"ltx file corrupted","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"litestream.go","lineNumber":35,"sourceCode":"\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 != \"\" {\n\t\treturn e.Op + \" ltx file \" + e.Path + \": \" + e.Err.Error()","sourceCodeStart":17,"sourceCodeEnd":53,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/litestream.go#L17-L53","documentation":"ErrLTXCorrupted indicates an LTX file failed structural verification (ltx.Decoder.Verify) or its header could not be decoded, meaning the transaction file is unreadable or truncated. Like checksum mismatch it is auto-recoverable and wrapped in LTXError with a recovery hint.","triggerScenarios":"db.go:634 dec.Verify() failing on an LTX file before applying it; db.go:1702 dec.DecodeHeader() failing during WAL apply — both wrap the underlying error with %w: %w into ErrLTXCorrupted.","commonSituations":"Disk full or I/O errors while writing LTX files, crashed process leaving truncated files, corrupted local .sqlite-litestream state, damaged objects in the replica storage.","solutions":["Run `litestream reset <db>` to discard corrupted local LTX state and recover from the replica","Enable auto-recover: true on the replica config","Check disk space (ErrDiskFull often precedes corruption)","Delete the .sqlite-litestream directory and restart as a manual fallback"],"exampleFix":"# before\nlitestream run -config /etc/litestream.yml   # keeps failing on corrupt file\n# after\nlitestream reset /path/to/db.sqlite\nlitestream run -config /etc/litestream.yml","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isLTXCorruption(err error) bool {\n    return errors.Is(err, litestream.ErrLTXCorrupted)\n}","tryCatchPattern":"if err := db.Sync(ctx); err != nil {\n    if errors.Is(err, litestream.ErrLTXCorrupted) {\n        slog.Error(\"corrupt LTX detected; run 'litestream reset' or rely on auto-recover\", \"err\", err)\n        return litestream.Reset(ctx, dbPath)\n    }\n    return err\n}","preventionTips":["Enable auto-recover: true on the replica","Alert on disk-full conditions that cause truncated writes","Avoid killing litestream mid-write (use graceful shutdown)","Periodically verify replica files with `litestream ltx`"],"tags":["ltx","corruption","ltx-format","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"}