{"record":{"id":"e85e2f0bf31e2531","repo":"benbjohnson/litestream","slug":"list-generations-w","errorCode":null,"errorMessage":"list generations: %w","messagePattern":"list generations: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"replica.go","lineNumber":1090,"sourceCode":"\n\t// Validate options.\n\tif opt.OutputPath == \"\" {\n\t\treturn fmt.Errorf(\"output path required\")\n\t} else if opt.IntegrityCheck != IntegrityCheckNone && opt.IntegrityCheck != IntegrityCheckQuick && opt.IntegrityCheck != IntegrityCheckFull {\n\t\treturn fmt.Errorf(\"unsupported integrity check mode: %d\", opt.IntegrityCheck)\n\t}\n\n\t// Ensure output path does not already exist.\n\tif _, err := os.Stat(opt.OutputPath); err == nil {\n\t\treturn fmt.Errorf(\"cannot restore, output path already exists: %s\", opt.OutputPath)\n\t} else if !os.IsNotExist(err) {\n\t\treturn err\n\t}\n\n\t// Find all generations.\n\tgenerations, err := client.GenerationsV3(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"list generations: %w\", err)\n\t}\n\tif len(generations) == 0 {\n\t\treturn ErrNoSnapshots\n\t}\n\n\t// Collect all snapshots across all generations.\n\tvar allSnapshots []SnapshotInfoV3\n\tfor _, gen := range generations {\n\t\tsnapshots, err := client.SnapshotsV3(ctx, gen)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"list snapshots for generation %s: %w\", gen, err)\n\t\t}\n\t\tallSnapshots = append(allSnapshots, snapshots...)\n\t}\n\tif len(allSnapshots) == 0 {\n\t\treturn ErrNoSnapshots\n\t}\n","sourceCodeStart":1072,"sourceCodeEnd":1108,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/replica.go#L1072-L1108","documentation":"RestoreV3 enumerates backup generations via client.GenerationsV3(ctx); if that remote listing fails the underlying error is wrapped as 'list generations: %w'. It is a transport/storage error while talking to the replica client backend (S3, file system, etc.), not an options problem. An empty (but successful) listing instead yields ErrNoSnapshots.","triggerScenarios":"Calling Replica.Restore against a v0.3.x replica when the storage backend is unreachable, credentials are wrong, the bucket/container does not exist, or the backend returned a transient error while listing generation directories.","commonSituations":"Offline or misconfigured network during disaster recovery; expired S3 credentials or wrong region; pointing the client at the wrong bucket after a config change; S3 outage or throttling during list requests.","solutions":["Inspect the wrapped cause (%w) with errors.Unwrap/%v to see the storage error (auth, DNS, 4xx/5xx) and fix that backend issue","Verify replica client config: bucket, endpoint, region, credentials, network reachability","Retry the restore; generation listing is read-only and safe to repeat","Run litestream ltx or list the bucket manually to confirm generations are visible"],"exampleFix":"// before\nerr := replica.Restore(ctx, opt) // opaque 'list generations: ...'\n// after\nif err := replica.Restore(ctx, opt); err != nil {\n    var ctxErr context.Error\n    log.Printf(\"restore failed, cause=%v\", errors.Unwrap(err)) // surface backend error\n    _ = ctxErr\n    return err\n}","handlingStrategy":"retry","validationCode":"// preflight: verify the backend is reachable and listable before restore\nif _, err := client.GenerationsV3(ctx); err != nil {\n    return fmt.Errorf(\"replica backend unreachable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := replica.Restore(ctx, opt); err != nil {\n    var ne net.Error\n    if errors.As(err, &ne) || strings.Contains(err.Error(), \"list generations\") {\n        return retryWithBackoff(ctx, 3, func() error { return replica.Restore(ctx, opt) })\n    }\n    return err\n}","preventionTips":["Verify bucket/container name, region, endpoint, and credentials in the replica config before DR","Run periodic restore drills to catch auth/network misconfigurations early","Use exponential backoff for transient storage errors","Confirm network/VPN/proxy access to the storage endpoint from the restore host"],"tags":["go","restore","storage","network","s3"],"backgroundTag":"http-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"}