{"record":{"id":"c5212a5b1a767fce","repo":"benbjohnson/litestream","slug":"cannot-specify-url-path-for-oss-replica","errorCode":null,"errorMessage":"cannot specify url & path for oss replica","messagePattern":"cannot specify url & path for oss replica","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/main.go","lineNumber":1992,"sourceCode":"\t// Set connection options with defaults\n\tif c.MaxReconnects != nil {\n\t\tclient.MaxReconnects = *c.MaxReconnects\n\t}\n\tif c.ReconnectWait != nil {\n\t\tclient.ReconnectWait = *c.ReconnectWait\n\t}\n\tif c.Timeout != nil {\n\t\tclient.Timeout = *c.Timeout\n\t}\n\n\treturn client, nil\n}\n\n// newOSSReplicaClientFromConfig returns a new instance of oss.ReplicaClient built from config.\nfunc newOSSReplicaClientFromConfig(c *ReplicaConfig, _ *litestream.Replica) (_ *oss.ReplicaClient, err error) {\n\t// Ensure URL & constituent parts are not both specified.\n\tif c.URL != \"\" && c.Path != \"\" {\n\t\treturn nil, fmt.Errorf(\"cannot specify url & path for oss replica\")\n\t} else if c.URL != \"\" && c.Bucket != \"\" {\n\t\treturn nil, fmt.Errorf(\"cannot specify url & bucket for oss replica\")\n\t}\n\n\tbucket, configPath := c.Bucket, c.Path\n\tregion, endpoint := c.Region, c.Endpoint\n\n\t// Apply settings from URL, if specified.\n\tif c.URL != \"\" {\n\t\t_, host, upath, err := litestream.ParseReplicaURL(c.URL)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}\n\n\t\tvar (\n\t\t\tubucket string\n\t\t\turegion string\n\t\t)","sourceCodeStart":1974,"sourceCodeEnd":2010,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/main.go#L1974-L2010","documentation":"newOSSReplicaClientFromConfig rejects configs that specify both `url` and `path` for an Alibaba Cloud OSS replica. These are two ways to describe the same location, and Litestream refuses the ambiguity rather than guessing precedence.","triggerScenarios":"A replica config with `url: oss://bucket/prefix` AND `path: prefix` set at the same time.","commonSituations":"Adding a `path` field to an existing URL-based config when switching from full-URL to component-style configuration, or merging two config files.","solutions":["Remove the `path` field and keep only `url`.","Or remove `url` and specify `bucket` + `path` (plus `region`/`endpoint`) as separate fields.","Derive the path from the URL and delete the redundant key."],"exampleFix":"# before\nreplicas:\n  - url: oss://mybucket/backups\n    path: backups\n# after\nreplicas:\n  - url: oss://mybucket/backups","handlingStrategy":"validation","validationCode":"// Reject ambiguous OSS config before invoking litestream\nif cfg.URL != \"\" && cfg.Path != \"\" {\n    return fmt.Errorf(\"oss replica: choose either url or path, not both\")\n}","typeGuard":null,"tryCatchPattern":"if err := runReplicate(); err != nil {\n    if strings.Contains(err.Error(), \"cannot specify url & path\") {\n        // strip the redundant field from config\n    }\n}","preventionTips":["Pick one config style (URL-based or component-based) per replica and stick to it.","When migrating configs between backends, delete leftover keys rather than commenting them."],"tags":["oss","config","ambiguous"],"backgroundTag":"conflicting-config-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"}