{"record":{"id":"989480ad02d750f6","repo":"benbjohnson/litestream","slug":"no-matching-backup-files-available","errorCode":null,"errorMessage":"no matching backup files available","messagePattern":"no matching backup files available","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/restore.go","lineNumber":121,"sourceCode":"\t\t} else if err != nil {\n\t\t\treturn err\n\t\t}\n\t} else {\n\t\tif *configPath == \"\" {\n\t\t\t*configPath = DefaultConfigPath()\n\t\t}\n\t\tif r, err = c.loadFromConfig(ctx, fs.Arg(0), *configPath, !*noExpandEnv, *ifDBNotExists, &opt); errors.Is(err, errSkipDBExists) {\n\t\t\tslog.Info(\"database already exists, skipping\")\n\t\t\treturn nil\n\t\t} else if err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\tif *dryRun {\n\t\tplan, err := c.dryRunPlan(ctx, fs.Arg(0), r, opt)\n\t\tif errors.Is(err, litestream.ErrTxNotAvailable) {\n\t\t\treturn fmt.Errorf(\"no matching backup files available\")\n\t\t} else if err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif *jsonOutput {\n\t\t\toutput, err := json.MarshalIndent(plan, \"\", \"  \")\n\t\t\tif err != nil {\n\t\t\t\treturn fmt.Errorf(\"failed to format response: %w\", err)\n\t\t\t}\n\t\t\tfmt.Println(string(output))\n\t\t\treturn nil\n\t\t}\n\t\tc.printDryRunPlan(plan)\n\t\treturn nil\n\t}\n\n\tif !opt.Follow {\n\t\tif err := c.prepareOutputPath(opt.OutputPath, *force); err != nil {\n\t\t\treturn err","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/restore.go#L103-L139","documentation":"With --dry-run, restore computes a plan via c.dryRunPlan; if the planner reports litestream.ErrTxNotAvailable, meaning no backup files in the replica match the requested timestamp/TXID constraints, the command converts it into the friendlier message \"no matching backup files available\". Nothing was restored; the replica simply lacks a usable snapshot/transaction for the request.","triggerScenarios":"`litestream restore --dry-run ...` where the target replica has no snapshots, the requested -timestamp predates the earliest backup or exceeds retention, or a -txid is given that doesn't exist in the replica.","commonSituations":"Retention window expired so old snapshots were deleted from S3; wrong bucket/prefix (empty or unrelated replica); asking for a timestamp from before replication was first set up; replica URL typo pointing at an empty prefix.","solutions":["List what is actually available (e.g. `litestream ltx -level all` or a dry-run without tight constraints) to see the replica's coverage","Omit or widen -timestamp/-txid to restore the latest available state instead","Verify the replica URL/bucket/prefix points at the right replication target","Check retention settings — the needed snapshot may have been deleted; restore from another replica or accept a newer point-in-time"],"exampleFix":"// before (timestamp before any backup existed)\nlitestream restore --dry-run -timestamp 2020-01-01T00:00:00Z s3://bucket/prefix\n// after (latest available)\nlitestream restore --dry-run s3://bucket/prefix","handlingStrategy":"fallback","validationCode":"// Probe availability before requesting a specific point in time\nplan, err := dryRunPlan(ctx, url, nil, optNoConstraints)\nif errors.Is(err, litestream.ErrTxNotAvailable) {\n    return fmt.Errorf(\"replica %s has no backups at all\", url)\n}","typeGuard":null,"tryCatchPattern":"plan, err := dryRunPlan(ctx, arg, r, opt)\nif errors.Is(err, litestream.ErrTxNotAvailable) {\n    // retry without -timestamp/-txid to get latest available\n    opt.Timestamp, opt.TxID = time.Time{}, zeroTxID\n    plan, err = dryRunPlan(ctx, arg, r, opt)\n}","preventionTips":["Run a dry-run without constraints first to confirm replica coverage","Monitor replication health so empty replicas are caught early","Align retention/lifecycle rules with your restore point-in-time requirements"],"tags":["restore","backup","point-in-time","empty-result"],"backgroundTag":"resource-not-found","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"}