{"record":{"id":"e8900403d944c9d7","repo":"benbjohnson/litestream","slug":"fetch-l0-files-w-e89004","errorCode":null,"errorMessage":"fetch l0 files: %w","messagePattern":"fetch l0 files: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"db.go","lineNumber":3053,"sourceCode":"\t\tinfo := itr.Item()\n\t\tif info.MaxTXID > maxL1TXID {\n\t\t\tmaxL1TXID = info.MaxTXID\n\t\t}\n\t}\n\tif err := itr.Close(); err != nil {\n\t\treturn fmt.Errorf(\"close l1 iterator: %w\", err)\n\t}\n\tif maxL1TXID == 0 {\n\t\tinternal.L0RetentionGaugeVec.WithLabelValues(dbName, \"eligible\").Set(0)\n\t\tinternal.L0RetentionGaugeVec.WithLabelValues(dbName, \"not_compacted\").Set(0)\n\t\tinternal.L0RetentionGaugeVec.WithLabelValues(dbName, \"too_recent\").Set(0)\n\t\treturn nil\n\t}\n\n\tthreshold := time.Now().Add(-db.L0Retention)\n\titr, err = db.Replica.Client.LTXFiles(ctx, 0, 0, false)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"fetch l0 files: %w\", err)\n\t}\n\tdefer itr.Close()\n\n\tvar (\n\t\tdeleted           []*ltx.FileInfo\n\t\tlastInfo          *ltx.FileInfo\n\t\tprocessedAll      = true\n\t\ttotalFiles        int\n\t\tnotCompactedCount int\n\t\ttooRecentCount    int\n\t)\n\tfor itr.Next() {\n\t\tinfo := itr.Item()\n\t\tlastInfo = info\n\t\ttotalFiles++\n\n\t\tcreatedAt := info.CreatedAt\n\t\tif createdAt.IsZero() {","sourceCodeStart":3035,"sourceCodeEnd":3071,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/db.go#L3035-L3071","documentation":"Wraps a failure from Replica.Client.LTXFiles when listing level-0 LTX files during L0 retention enforcement. Without a complete L0 listing the library cannot decide which files expired past L0Retention, so the retention cycle aborts.","triggerScenarios":"The L0 retention pass (db.go:3053) listing L0 files when the replica backend fails: network outage, expired credentials, wrong path prefix, or backend 5xx/throttling.","commonSituations":"High-churn databases with many L0 files triggering S3 listing throttling; credential rotation mid-run; proxy or VPC-endpoint failures.","solutions":["Verify storage credentials and endpoint reachability.","Inspect the wrapped error (AccessDenied, Throttling, timeout) and fix the root cause.","Retry the retention run with backoff; listing is read-only.","For throttling, reduce listing concurrency or configure SDK retry settings.","Validate the replica URL/path so listings target the correct prefix."],"exampleFix":"// before\nitr, err := db.Replica.Client.LTXFiles(ctx, 0, 0, false)\nif err != nil { return fmt.Errorf(\"fetch l0 files: %w\", err) }\n// after (pre-flight)\nif err := db.Replica.Client.Init(ctx); err != nil { return fmt.Errorf(\"init replica: %w\", err) }\nitr, err := db.Replica.Client.LTXFiles(ctx, 0, 0, false)\nif err != nil { return fmt.Errorf(\"fetch l0 files: %w\", err) }","handlingStrategy":"retry","validationCode":"if err := db.Replica.Client.Init(ctx); err != nil { return fmt.Errorf(\"replica init failed: %w\", err) }","typeGuard":null,"tryCatchPattern":"itr, err := db.Replica.Client.LTXFiles(ctx, 0, 0, false)\nif err != nil {\n    if isTransient(err) { return retryWithBackoff(ctx) }\n    return fmt.Errorf(\"fetch l0 files: %w\", err)\n}","preventionTips":["Pre-flight the replica before retention cycles.","Alert on listing throttling for high-churn databases.","Validate the replica path prefix after config changes."],"tags":["storage","retention","listing","network"],"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-14T00:17:10.932Z"}