{"record":{"id":"6f7810b92ff42ec4","repo":"benbjohnson/litestream","slug":"output-path-required","errorCode":null,"errorMessage":"output path required","messagePattern":"output path required","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"replica.go","lineNumber":611,"sourceCode":"\n\treturn updatedAt, nil\n}\n\n// Replica restores the database from a replica based on the options given.\n// This method will restore into opt.OutputPath, if specified, or into the\n// DB's original database path. It can optionally restore from a specific\n// replica or it will automatically choose the best one. Finally,\n// a timestamp can be specified to restore the database to a specific\n// point-in-time.\n//\n// When the replica contains both v0.3.x and LTX format backups, this method\n// compares snapshots from both formats and uses whichever has the better backup:\n// - With timestamp: uses the format with the most recent snapshot before timestamp\n// - Without timestamp: uses the format with the most recent backup overall\nfunc (r *Replica) Restore(ctx context.Context, opt RestoreOptions) (err error) {\n\t// Validate options.\n\tif opt.OutputPath == \"\" {\n\t\treturn fmt.Errorf(\"output path required\")\n\t} else if opt.TXID != 0 && !opt.Timestamp.IsZero() {\n\t\treturn fmt.Errorf(\"cannot specify index & timestamp to restore\")\n\t} else if opt.Follow && opt.TXID != 0 {\n\t\treturn fmt.Errorf(\"cannot use follow mode with -txid\")\n\t} else if opt.Follow && !opt.Timestamp.IsZero() {\n\t\treturn fmt.Errorf(\"cannot use follow mode with -timestamp\")\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// In follow mode, if the database already exists, attempt crash recovery\n\t// by reading the last applied TXID from the sidecar file.\n\tif opt.Follow {\n\t\tif _, statErr := os.Stat(opt.OutputPath); statErr == nil {\n\t\t\ttxid, readErr := ReadTXIDFile(opt.OutputPath)\n\t\t\tif readErr != nil {\n\t\t\t\treturn fmt.Errorf(\"read txid file for crash recovery: %w\", readErr)\n\t\t\t}","sourceCodeStart":593,"sourceCodeEnd":629,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/replica.go#L593-L629","documentation":"Replica.Restore validates RestoreOptions before doing any work. If opt.OutputPath is empty there is no destination for the restored database file, so restore immediately fails with this error. It is a pure argument-validation error — no storage or database access happens first.","triggerScenarios":"Calling Replica.Restore (directly or via Run, EnsureExists, tests) with RestoreOptions that leaves OutputPath unset — e.g. programmatically building RestoreOptions{} without setting OutputPath.","commonSituations":"Programmatic restore code constructing RestoreOptions with only TXID/Timestamp; a CLI path that failed to bind the -o flag value; EnsureExists invoked with a zero-value options struct.","solutions":["Set OutputPath in RestoreOptions to the target database file path before calling Restore.","If using the CLI, pass the -o flag with a writable destination path.","Ensure the destination directory exists and is writable before restoring."],"exampleFix":"// before\nerr := replica.Restore(ctx, litestream.RestoreOptions{TXID: txid})\n\n// after\nerr := replica.Restore(ctx, litestream.RestoreOptions{\n    TXID:       txid,\n    OutputPath: \"/var/lib/app/db.sqlite\",\n})","handlingStrategy":"validation","validationCode":"if opt.OutputPath == \"\" {\n    return fmt.Errorf(\"OutputPath must be set before Restore\")\n}\nif err := os.MkdirAll(filepath.Dir(opt.OutputPath), 0o755); err != nil {\n    return err\n}","typeGuard":null,"tryCatchPattern":"if err := replica.Restore(ctx, opt); err != nil && strings.Contains(err.Error(), \"output path required\") {\n    // fix option construction; this is a programmer/config error, not transient\n}","preventionTips":["Always set OutputPath when building RestoreOptions programmatically","Add a config-level check that the restore destination is provided and writable","Create the destination directory before calling Restore"],"tags":["restore","validation","required-argument"],"backgroundTag":"missing-required-argument","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"}