{"record":{"id":"cc4fb4720ceac5c7","repo":"benbjohnson/litestream","slug":"ltx-file-missing","errorCode":null,"errorMessage":"ltx file missing","messagePattern":"ltx file missing","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"litestream.go","lineNumber":36,"sourceCode":"// 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()\n\t}","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/litestream.go#L18-L54","documentation":"ErrLTXMissing indicates a required LTX file is absent from local state or the replica — typically the next transaction in the sequence. It is auto-recoverable: LTXError.IsAutoRecoverable returns true for it, and NewLTXError attaches a hint to run `litestream reset <db>`.","triggerScenarios":"Opening/applying the next LTX position when the file does not exist locally (os.IsNotExist) or errors.Is(err, ErrLTXMissing); common after VACUUM, manual checkpoints, or local state deletion out from under a running instance.","commonSituations":"Running VACUUM or manual SQLite checkpoints outside litestream which invalidate tracked positions, deleting part of .sqlite-litestream manually, retention/lifecycle rules removing objects still referenced locally.","solutions":["Run `litestream reset <db>` to rebuild local state from the replica","Enable auto-recover: true on the replica so resets happen automatically","Avoid manual VACUUM/checkpoints on databases managed by litestream, or restart litestream after them","Check storage lifecycle rules so objects are not deleted while still needed"],"exampleFix":"# before\nsqlite3 db.sqlite 'VACUUM;'   # while litestream runs -> ErrLTXMissing\n# after\nlitestream reset /path/to/db.sqlite && litestream run -config /etc/litestream.yml","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"func isLTXMissing(err error) bool {\n    return os.IsNotExist(err) || errors.Is(err, litestream.ErrLTXMissing)\n}","tryCatchPattern":"if err := db.Sync(ctx); err != nil {\n    if isLTXMissing(err) {\n        // hint from NewLTXError: reset and recover from replica\n        return litestream.Reset(ctx, dbPath)\n    }\n    return err\n}","preventionTips":["Never manually delete files inside .sqlite-litestream","Restart litestream after VACUUM or manual checkpoints","Align storage lifecycle rules with litestream retention","Enable auto-recover: true to handle missing files automatically"],"tags":["ltx","missing-file","recovery","reset"],"backgroundTag":"resource-not-found","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"}