{"record":{"id":"82c01e068b6b3949","repo":"benbjohnson/litestream","slug":"parse-txid-file-w","errorCode":null,"errorMessage":"parse txid file: %w","messagePattern":"parse txid file: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"replica.go","lineNumber":1767,"sourceCode":"\t}\n\treturn nil\n}\n\n// ReadTXIDFile reads the TXID from a sidecar file at <outputPath>-txid.\n// Returns 0, nil if the file does not exist (first run).\nfunc ReadTXIDFile(outputPath string) (ltx.TXID, error) {\n\ttxidPath := TXIDPath(outputPath)\n\n\tdata, err := os.ReadFile(txidPath)\n\tif os.IsNotExist(err) {\n\t\treturn 0, nil\n\t} else if err != nil {\n\t\treturn 0, fmt.Errorf(\"read txid file: %w\", err)\n\t}\n\n\ttxid, err := ltx.ParseTXID(strings.TrimSpace(string(data)))\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"parse txid file: %w\", err)\n\t}\n\n\treturn txid, nil\n}\n\n// ValidationError represents a single validation issue.\ntype ValidationError struct {\n\tLevel    int           // compaction level\n\tType     string        // \"gap\", \"overlap\", or \"unsorted\"\n\tMessage  string        // human-readable description\n\tPrevFile *ltx.FileInfo // previous file\n\tCurrFile *ltx.FileInfo // current file that caused error\n}\n\n// ValidateLevel checks LTX files at the given level are sorted and contiguous.\n// Returns a slice of validation errors (empty if valid).\nfunc (r *Replica) ValidateLevel(ctx context.Context, level int) ([]ValidationError, error) {\n\titr, err := r.Client.LTXFiles(ctx, level, 0, false)","sourceCodeStart":1749,"sourceCodeEnd":1785,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/replica.go#L1749-L1785","documentation":"After reading the sidecar file, ReadTXIDFile parses its trimmed contents with ltx.ParseTXID. This error means the file content is not a valid TXID string. Since the file is written atomically (temp + fsync + rename), invalid content usually indicates manual tampering, truncation by another tool, or a file created by an incompatible version.","triggerScenarios":"os.ReadFile succeeded on '<outputPath>-txid' but ltx.ParseTXID rejects the trimmed content: empty file, HTML/error text written there by mistake, a truncated partial write from external tooling, or a binary blob in place of the expected textual TXID (e.g. '0000000000000001').","commonSituations":"A deployment script or health-check accidentally overwrote the -txid file; editor or log redirection wrote garbage into it; disk corruption; mixing outputs from different litestream versions.","solutions":["Inspect the file content (cat <db>-txid); it should contain a single zero-padded TXID like 0000000000000042","If invalid, delete the sidecar file — ReadTXIDFile treats a missing file as first-run and litestream will re-derive state via restore/sync","Re-restore the database from the replica to rebuild consistent local state, or use 'litestream reset' to clear corrupted local LTX state","Stop any scripts/tools that write to '<db>-txid' or paths adjacent to the database"],"exampleFix":"# before: manually editing the sidecar file\necho \"latest\" > my.db-txid\n# after: let litestream manage it\nrm my.db-txid            # first-run semantics: treated as 0\nlitestream restore -o my.db mydb.db","handlingStrategy":"validation","validationCode":"data, err := os.ReadFile(TXIDPath(outputPath))\nif err == nil {\n    if _, perr := ltx.ParseTXID(strings.TrimSpace(string(data))); perr != nil {\n        // treat as corrupt: remove so ReadTXIDFile returns first-run semantics\n        os.Remove(TXIDPath(outputPath))\n    }\n}","typeGuard":"func validTXIDFile(path string) bool {\n    b, err := os.ReadFile(path)\n    if err != nil { return false }\n    _, err = ltx.ParseTXID(strings.TrimSpace(string(b)))\n    return err == nil\n}","tryCatchPattern":"txid, err := ReadTXIDFile(outputPath)\nif err != nil {\n    var parseErr *strconv.ErrSyntax\n    if errors.As(err, &parseErr) {\n        os.Remove(TXIDPath(outputPath)) // reset to first-run\n        txid, err = 0, nil\n    }\n}","preventionTips":["Never write to '<db>-txid' from scripts or editors","Exclude '*-txid' files from log redirections and templating","After restoring from backups, validate sidecar contents before starting","Use 'litestream reset' rather than hand-editing state files"],"tags":["parsing","txid","corruption","litestream"],"backgroundTag":"invalid-argument-format","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"}