{"record":{"id":"ee62903b4bd56dcf","repo":"benbjohnson/litestream","slug":"file-replica-path-required-ee6290","errorCode":null,"errorMessage":"file replica path required","messagePattern":"file replica path required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"file/replica_client.go","lineNumber":57,"sourceCode":"\n// NewReplicaClient returns a new instance of ReplicaClient.\nfunc NewReplicaClient(path string) *ReplicaClient {\n\treturn &ReplicaClient{\n\t\tlogger: slog.Default().WithGroup(ReplicaClientType),\n\t\tpath:   path,\n\t}\n}\n\nfunc (c *ReplicaClient) SetLogger(logger *slog.Logger) {\n\tc.logger = logger.WithGroup(ReplicaClientType)\n}\n\n// NewReplicaClientFromURL creates a new ReplicaClient from URL components.\n// This is used by the replica client factory registration.\nfunc NewReplicaClientFromURL(scheme, host, urlPath string, query url.Values, userinfo *url.Userinfo) (litestream.ReplicaClient, error) {\n\t// For file URLs, the path is the full path\n\tif urlPath == \"\" {\n\t\treturn nil, fmt.Errorf(\"file replica path required\")\n\t}\n\treturn NewReplicaClient(urlPath), nil\n}\n\n// db returns the database, if available.\nfunc (c *ReplicaClient) db() *litestream.DB {\n\tif c.Replica == nil {\n\t\treturn nil\n\t}\n\treturn c.Replica.DB()\n}\n\n// Type returns \"file\" as the client type.\nfunc (c *ReplicaClient) Type() string {\n\treturn ReplicaClientType\n}\n\n// Init is a no-op for file replica client as no initialization is required.","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/file/replica_client.go#L39-L75","documentation":"The file replica client factory requires a path component in a file:// replica URL because for file URLs the path is where replica data is stored. NewReplicaClientFromURL returns this error when a file-scheme URL has an empty path, e.g. file:// with no target directory.","triggerScenarios":"Configuring a file replica with URL like file:// (no path), or programmatically registering a replica whose URL path is empty, then instantiating the client via the URL factory.","commonSituations":"YAML config with `url: file://` missing the directory; templated config where a path variable expanded to empty; hand-built url.URL with only the scheme set.","solutions":["Set an absolute directory path in the file replica URL, e.g. file:///var/lib/litestream/db.","Check config expansion ($ENV_VAR, $PID) didn't produce an empty path segment.","Validate the URL before creating the replica: require a non-empty Path for the file scheme.","When building URLs programmatically, set url.Path to the intended directory."],"exampleFix":"// before (litestream.yml)\nreplicas:\n  - url: file://\n// after\nreplicas:\n  - url: file:///var/backups/litestream/mydb","handlingStrategy":"validation","validationCode":"u, err := url.Parse(replicaURL)\nif err != nil || u.Scheme != \"file\" { return fmt.Errorf(\"not a file replica URL\") }\nif u.Path == \"\" { return fmt.Errorf(\"file replica path required\") }","typeGuard":"func validFileReplicaURL(u *url.URL) bool { return u != nil && u.Scheme == \"file\" && u.Path != \"\" }","tryCatchPattern":"if _, err := NewReplicaClientFromURL(\"file\", u.Host, u.Path, u.Query(), u.User); err != nil {\n    return fmt.Errorf(\"invalid file replica URL %q: %w\", replicaURL, err)\n}","preventionTips":["Always use absolute paths in file:// replica URLs.","Check env-var expansion didn't blank the path at config load.","Validate all replica URLs at startup before registering replicas."],"tags":["config","url","file-replica","validation"],"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-14T00:17:10.932Z"}