{"record":{"id":"84439563ed1466ae","repo":"benbjohnson/litestream","slug":"cannot-specify-url-path-for-file-replica","errorCode":null,"errorMessage":"cannot specify url & path for file replica","messagePattern":"cannot specify url & path for file replica","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/main.go","lineNumber":1424,"sourceCode":"\t\t}\n\tcase \"oss\":\n\t\tif r.Client, err = newOSSReplicaClientFromConfig(c, r); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"unknown replica type in config: %q\", c.ReplicaType())\n\t}\n\n\tr.Client.SetLogger(r.Logger())\n\n\treturn r, nil\n}\n\n// newFileReplicaClientFromConfig returns a new instance of file.ReplicaClient built from config.\nfunc newFileReplicaClientFromConfig(c *ReplicaConfig, r *litestream.Replica) (_ *file.ReplicaClient, err error) {\n\t// Ensure URL & path are not both specified.\n\tif c.URL != \"\" && c.Path != \"\" {\n\t\treturn nil, fmt.Errorf(\"cannot specify url & path for file replica\")\n\t}\n\n\t// Parse configPath from URL, if specified.\n\tconfigPath := c.Path\n\tif c.URL != \"\" {\n\t\tif _, _, configPath, err = litestream.ParseReplicaURL(c.URL); err != nil {\n\t\t\treturn nil, err\n\t\t}\n\t}\n\n\t// Ensure path is set explicitly or derived from URL field.\n\tif configPath == \"\" {\n\t\treturn nil, fmt.Errorf(\"file replica path required\")\n\t}\n\n\t// Expand home prefix and return absolute path.\n\tif configPath, err = expand(configPath); err != nil {\n\t\treturn nil, err","sourceCodeStart":1406,"sourceCodeEnd":1442,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/main.go#L1406-L1442","documentation":"A file replica may be described either by a `url` (file://...) or a `path`, but newFileReplicaClientFromConfig forbids specifying both, since the source of the destination directory would be ambiguous.","triggerScenarios":"Replica config has both a non-empty `url` (e.g. `file:///backups/db`) and a non-empty `path` (e.g. `path: /backups/db`) for a file-type replica.","commonSituations":"Merging an old path-based config with a new url-based one; template-generated config where defaults set `path` and users also set `url`.","solutions":["Delete the `path` field and keep only `url`","Or delete `url` and keep only `path`","Keep exactly one of the two fields per file replica entry"],"exampleFix":"# before\nreplicas:\n  - url: file:///backups/db\n    path: /backups/db\n# after\nreplicas:\n  - url: file:///backups/db","handlingStrategy":"validation","validationCode":"if r.URL != \"\" && r.Path != \"\" {\n    return errors.New(\"file replica: set either url or path, not both\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pick one convention (url preferred) per file replica","Ensure templating/defaults do not inject a path when url is set","Review merged configs for duplicated fields"],"tags":["config","replica","file","ambiguity"],"backgroundTag":"mutually-exclusive-options","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"}