{"record":{"id":"37cdf81ed0225003","repo":"benbjohnson/litestream","slug":"max-ltx-file-w","errorCode":null,"errorMessage":"max ltx file: %w","messagePattern":"max ltx file: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"replica.go","lineNumber":277,"sourceCode":"\t}\n\tr.Logger().Debug(\"ltx file uploaded\",\n\t\t\"level\", info.Level,\n\t\t\"minTXID\", info.MinTXID,\n\t\t\"maxTXID\", info.MaxTXID,\n\t\t\"size\", info.Size)\n\n\t// Track current position\n\t//replicaWALIndexGaugeVec.WithLabelValues(r.db.Path(), r.Name()).Set(float64(rd.Pos().Index))\n\t//replicaWALOffsetGaugeVec.WithLabelValues(r.db.Path(), r.Name()).Set(float64(rd.Pos().Offset))\n\n\treturn nil\n}\n\n// calcPos returns the last position saved to the replica for level 0.\nfunc (r *Replica) calcPos(ctx context.Context) (pos ltx.Pos, err error) {\n\tinfo, err := r.MaxLTXFileInfo(ctx, 0)\n\tif err != nil {\n\t\treturn pos, fmt.Errorf(\"max ltx file: %w\", err)\n\t}\n\treturn ltx.Pos{TXID: info.MaxTXID}, nil\n}\n\n// MaxLTXFileInfo returns metadata about the last LTX file for a given level.\n// Returns nil if no files exist for the level.\nfunc (r *Replica) MaxLTXFileInfo(ctx context.Context, level int) (info ltx.FileInfo, err error) {\n\t// Normal operation - use fast timestamps\n\titr, err := r.Client.LTXFiles(ctx, level, 0, false)\n\tif err != nil {\n\t\treturn info, err\n\t}\n\tdefer itr.Close()\n\n\tfor itr.Next() {\n\t\titem := itr.Item()\n\t\tif item.MaxTXID > info.MaxTXID {\n\t\t\tinfo = *item","sourceCodeStart":259,"sourceCodeEnd":295,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/replica.go#L259-L295","documentation":"calcPos determines the replica's level-0 position by querying the storage client for metadata about the newest LTX file (MaxLTXFileInfo). If that query fails, this error wraps it. Note that a 'no files found' condition is typically not an error — this error means the metadata lookup itself failed against the remote replica.","triggerScenarios":"Replica.SyncStatus or syncOnce calls calcPos, and r.MaxLTXFileInfo(ctx, 0) returns an error — the storage list/read operation fails (network error, auth failure, unexpected listing response).","commonSituations":"Cloud storage temporarily unreachable; IAM permissions missing for listing objects; misconfigured bucket path; storage client returning an unexpected response shape for an empty/new replica.","solutions":["Check the wrapped cause for the storage-client error and fix connectivity/permissions.","Verify the replica client config (bucket, prefix, endpoint) points at the right location.","Confirm the storage credentials allow listing LTX objects at level 0.","Retry; if the replica was freshly created with no backups, ensure your client version handles the empty case without erroring."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// verify listing access to level-0 LTX path before status/sync\ninfos, err := client.ListLTXFiles(ctx, 0)\nif err != nil {\n    return fmt.Errorf(\"replica storage unreachable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"pos, err := replica.CalcPos(ctx) // or SyncStatus\nif err != nil && strings.Contains(err.Error(), \"max ltx file\") {\n    // storage listing failed: check wrapped cause, retry with backoff\n}","preventionTips":["Grant storage credentials list+read permissions on the LTX prefix","Validate bucket/prefix config points to the right replica location","Treat transient listing errors with retry before alerting"],"tags":["replication","storage","metadata"],"backgroundTag":"database-query-failed","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"}