{"record":{"id":"38cfcfc14998145f","repo":"benbjohnson/litestream","slug":"fetch-ltx-files-w-38cfcf","errorCode":null,"errorMessage":"fetch ltx files: %w","messagePattern":"fetch ltx files: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"replica.go","lineNumber":1787,"sourceCode":"\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)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"fetch ltx files: %w\", err)\n\t}\n\tdefer itr.Close()\n\n\tvar errors []ValidationError\n\tvar prevInfo *ltx.FileInfo\n\n\tfor itr.Next() {\n\t\tinfo := itr.Item()\n\n\t\t// Skip first file - nothing to compare against\n\t\tif prevInfo == nil {\n\t\t\tprevInfo = info\n\t\t\tcontinue\n\t\t}\n\n\t\t// Check for sort order: curr.MinTXID should be >= prev.MinTXID\n\t\tif info.MinTXID < prevInfo.MinTXID {\n\t\t\terrors = append(errors, ValidationError{","sourceCodeStart":1769,"sourceCodeEnd":1805,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/replica.go#L1769-L1805","documentation":"Replica.ValidateLevel lists LTX files at a compaction level by calling r.Client.LTXFiles(ctx, level, 0, false) to obtain a file iterator. This error wraps a failure to open/enumerate the remote (or local) LTX file listing from the replica client, so validation cannot proceed and no ValidationError list is produced.","triggerScenarios":"Calling ValidateLevel (or validation commands that use it) when the storage backend's LTXFiles listing fails: S3/GS/Azure credentials invalid or expired, bucket/container missing, network unreachable, or the storage client was not initialized for that level.","commonSituations":"Wrong bucket name or region in litestream.yml; expired cloud credentials (IAM role rotated, token expired); firewall/egress blocking the storage endpoint; s3 replica with a path that no longer exists after a provider migration.","solutions":["Run 'litestream replicas' or check the replica URL to confirm storage configuration (bucket, prefix, region, endpoint)","Verify cloud credentials/permissions (s3:Get/List on the bucket prefix) and that they are not expired","Test network connectivity to the storage endpoint from the host running validation","Check that the compaction level passed to ValidateLevel is valid (0–9) and that files exist at that level"],"exampleFix":"// before\nitr, err := client.LTXFiles(ctx, level, 0, false)\n// after: verify connectivity and creds before validating\nif err := clientHelmetCheck(ctx, r.Client); err != nil { return err }\nitr, err := r.Client.LTXFiles(ctx, level, 0, false)\nif err != nil { return fmt.Errorf(\"fetch ltx files at level %d: %w\", level, err) }","handlingStrategy":"retry","validationCode":"// Validate replica config before calling ValidateLevel\nif r.Client == nil { return fmt.Errorf(\"replica client not initialized\") }\nctx, cancel := context.WithTimeout(ctx, 30*time.Second)\ndefer cancel()","typeGuard":"func clientReady(r *Replica) bool { return r != nil && r.Client != nil }","tryCatchPattern":"errs, err := r.ValidateLevel(ctx, level)\nif err != nil {\n    // transient storage/network failures: retry with backoff\n    errs, err = retryWithBackoff(3, func() ([]ValidationError, error) {\n        return r.ValidateLevel(ctx, level)\n    })\n}","preventionTips":["Validate storage config (bucket, region, endpoint, credentials) before validation runs","Use short timeouts and bounded retries for listing calls","Refresh cloud credentials/roles before long maintenance windows","Run 'litestream replicas' first as a cheap connectivity check"],"tags":["storage","replica-client","network","validation"],"backgroundTag":"api-request-failed","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"}