{"record":{"id":"c450fe5c06a71903","repo":"benbjohnson/litestream","slug":"parse-hydration-meta-w","errorCode":null,"errorMessage":"parse hydration meta: %w","messagePattern":"parse hydration meta: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"vfs.go","lineNumber":976,"sourceCode":"\t}\n\tif err := os.Remove(h.metaPath()); err != nil && !os.IsNotExist(err) {\n\t\treturn err\n\t}\n\treturn nil\n}\n\nfunc (h *Hydrator) metaPath() string {\n\treturn h.path + \".meta\"\n}\n\nfunc (h *Hydrator) loadMeta() (ltx.TXID, error) {\n\tdata, err := os.ReadFile(h.metaPath())\n\tif err != nil {\n\t\treturn 0, err\n\t}\n\tv, err := strconv.ParseUint(strings.TrimSpace(string(data)), 10, 64)\n\tif err != nil {\n\t\treturn 0, fmt.Errorf(\"parse hydration meta: %w\", err)\n\t}\n\treturn ltx.TXID(v), nil\n}\n\nfunc (h *Hydrator) saveMeta() error {\n\th.mu.Lock()\n\ttxid := h.txid\n\th.mu.Unlock()\n\n\tdir := filepath.Dir(h.metaPath())\n\ttmp, err := os.CreateTemp(dir, \".hydration-meta-*\")\n\tif err != nil {\n\t\treturn fmt.Errorf(\"create temp meta file: %w\", err)\n\t}\n\ttmpPath := tmp.Name()\n\n\tif _, err := fmt.Fprintf(tmp, \"%d\\n\", txid); err != nil {\n\t\tif closeErr := tmp.Close(); closeErr != nil {","sourceCodeStart":958,"sourceCodeEnd":994,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/vfs.go#L958-L994","documentation":"Hydrator.loadMeta parses the .meta sidecar file that stores the last hydrated TXID and wraps strconv.ParseUint failures as \"parse hydration meta\". The meta file must contain a single decimal TXID; any other content makes resuming hydration impossible.","triggerScenarios":"The <hydration-path>.meta file exists but contains corrupt/non-numeric content — e.g. an empty file from a crashed previous write, binary garbage, or manual edits; a version change altered the meta format.","commonSituations":"Power loss or kill -9 mid-write on older versions that wrote the meta non-atomically; leftover meta files from a different litestream version; someone opening the file in an editor and saving garbage.","solutions":["Inspect the .meta file next to the hydration file; delete it if it is empty or corrupt — litestream will fall back to a full re-hydration","Use litestream reset for the database to clear hydration state cleanly","Ensure all litestream instances use the same version so the meta format matches","Avoid manually editing generated .meta files"],"exampleFix":"// before: hard failure on corrupt meta\nv, err := strconv.ParseUint(strings.TrimSpace(string(data)), 10, 64)\nif err != nil {\n\treturn 0, fmt.Errorf(\"parse hydration meta: %w\", err)\n}\n// after: caller treats corrupt meta as 'no saved state'\ntxid, err := h.loadMeta()\nif err != nil {\n\ttxid = 0 // re-hydrate from scratch\n}","handlingStrategy":"validation","validationCode":"// validate meta before litestream reads it\nif data, err := os.ReadFile(hydrationPath + \".meta\"); err == nil {\n\tif _, err := strconv.ParseUint(strings.TrimSpace(string(data)), 10, 64); err != nil {\n\t\tos.Remove(hydrationPath + \".meta\") // force clean re-hydration\n\t}\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never hand-edit generated .meta files","Run consistent litestream versions across instances","Ensure clean shutdowns (SIGTERM) so atomic meta writes complete","Delete corrupt .meta files — the cost is only a full re-hydration, never data loss"],"tags":["parsing","filesystem","hydration"],"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-14T05:17:10.506Z"}