{"record":{"id":"97ab1ea29256bfb2","repo":"benbjohnson/litestream","slug":"replica-path-cannot-be-a-url-please-use-the-url","errorCode":null,"errorMessage":"replica path cannot be a url, please use the 'url' field instead: %s","messagePattern":"replica path cannot be a url, please use the 'url' field instead: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/main.go","lineNumber":1353,"sourceCode":"\t\trs.Age.Recipients = src.Age.Recipients\n\t}\n}\n\n// ReplicaConfig represents the configuration for a single replica in a database.\ntype ReplicaConfig struct {\n\tReplicaSettings `yaml:\",inline\"`\n\n\tType string `yaml:\"type\"` // \"file\", \"s3\"\n\tName string `yaml:\"name\"` // Deprecated\n\tPath string `yaml:\"path\"`\n\tURL  string `yaml:\"url\"`\n}\n\n// NewReplicaFromConfig instantiates a replica for a DB based on a config.\nfunc NewReplicaFromConfig(c *ReplicaConfig, db *litestream.DB) (_ *litestream.Replica, err error) {\n\t// Ensure user did not specify URL in path.\n\tif litestream.IsURL(c.Path) {\n\t\treturn nil, fmt.Errorf(\"replica path cannot be a url, please use the 'url' field instead: %s\", c.Path)\n\t}\n\n\t// Reject age encryption configuration as it's currently non-functional.\n\t// Age encryption support was removed during the LTX storage layer refactor\n\t// and has not been reimplemented. Accepting this config would silently\n\t// write plaintext data to remote storage instead of encrypted data.\n\t// See: https://github.com/benbjohnson/litestream/issues/790\n\tif len(c.Age.Identities) > 0 || len(c.Age.Recipients) > 0 {\n\t\treturn nil, fmt.Errorf(\"age encryption is not currently supported, if you need encryption please revert back to Litestream v0.3.x\")\n\t}\n\n\t// Build replica.\n\tr := litestream.NewReplica(db)\n\tif v := c.SyncInterval; v != nil {\n\t\tr.SyncInterval = *v\n\t}\n\tif v := c.MaxSyncLTXFiles; v != nil {\n\t\tr.MaxSyncLTXFiles = *v","sourceCodeStart":1335,"sourceCodeEnd":1371,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/main.go#L1335-L1371","documentation":"NewReplicaFromConfig rejects a replica config whose `path` field looks like a URL (litestream.IsURL). In modern Litestream, replica destinations are specified with `url`; a path containing \"://\" (or another URL-like form) indicates a stale config style and would be misinterpreted.","triggerScenarios":"Config contains `replicas: [{path: s3://bucket/db}]` or a top-level replica `path` starting with a scheme like `s3://`, `file://`, `gs://` — checked when the replica is instantiated at startup.","commonSituations":"Upgrading from v0.3.x where path-URLs were accepted; copying an example config that put the URL under `path`; mixing `path` and `url` conventions.","solutions":["Move the value from `path` to the `url` field of the replica config","Remove any scheme from `path`; keep only a relative directory path there if a path is needed at all","Run `litestream replicate -config <file>` again after fixing; this check fires at replica construction time"],"exampleFix":"# before\nreplicas:\n  - path: s3://mybucket/db\n# after\nreplicas:\n  - url: s3://mybucket/db","handlingStrategy":"validation","validationCode":"for _, r := range cfg.Replicas {\n    if litestream.IsURL(r.Path) {\n        return fmt.Errorf(\"replica %q: move path %q to the url field\", r.Name, r.Path)\n    }\n}","typeGuard":"func isURL(s string) bool { return strings.Contains(s, \"://\") }","tryCatchPattern":null,"preventionTips":["Always use `url` for replica destinations; reserve `path` for relative dirs","When migrating from v0.3.x, rewrite path-URLs to url fields","Grep configs for `path:.*://` in CI"],"tags":["config","replica","url","migration"],"backgroundTag":"invalid-config-value","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"}