{"record":{"id":"e41bfb07f469b9c4","repo":"benbjohnson/litestream","slug":"bucket-required-for-nats-replica-url","errorCode":null,"errorMessage":"bucket required for nats replica URL","messagePattern":"bucket required for nats replica URL","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nats/replica_client.go","lineNumber":116,"sourceCode":"// URL format: nats://[user:pass@]host[:port]/bucket\nfunc NewReplicaClientFromURL(scheme, host, urlPath string, query url.Values, userinfo *url.Userinfo) (litestream.ReplicaClient, error) {\n\tclient := NewReplicaClient()\n\n\t// Reconstruct URL without bucket path\n\tif host != \"\" {\n\t\tclient.URL = fmt.Sprintf(\"nats://%s\", host)\n\t}\n\n\t// Extract credentials from userinfo if present\n\tif userinfo != nil {\n\t\tclient.Username = userinfo.Username()\n\t\tclient.Password, _ = userinfo.Password()\n\t}\n\n\t// Extract bucket name from path\n\tbucket := strings.Trim(urlPath, \"/\")\n\tif bucket == \"\" {\n\t\treturn nil, fmt.Errorf(\"bucket required for nats replica URL\")\n\t}\n\tclient.BucketName = bucket\n\n\treturn client, nil\n}\n\n// Type returns \"nats\" as the client type.\nfunc (c *ReplicaClient) Type() string {\n\treturn ReplicaClientType\n}\n\n// Init initializes the connection to NATS JetStream. No-op if already initialized.\nfunc (c *ReplicaClient) Init(ctx context.Context) error {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\n\tif c.objectStore != nil {\n\t\treturn nil","sourceCodeStart":98,"sourceCodeEnd":134,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/nats/replica_client.go#L98-L134","documentation":"NewReplicaClientFromURL parses a NATS replica URL (nats://user:pass@host:port/bucket) and requires the URL path to name the JetStream object-store bucket. This error is returned when the URL has no path component, because the client cannot know which bucket to store LTX files in.","triggerScenarios":"Configuring a replica URL like `nats://localhost:4222` or `nats://localhost:4222/` with an empty path, then calling NewReplicaClientFromURL (directly or via litestream config loading).","commonSituations":"Copy-pasting a plain NATS server address into the litestream config `url` field; forgetting the bucket suffix when migrating from S3-style URLs; env var expansion producing an empty path.","solutions":["Append the bucket name to the URL path: `nats://host:4222/mybucket`","Pre-create the bucket with the NATS CLI (`nats object add mybucket`) and use the same name in the URL","Check the resolved config/env value — a truncated URL may drop the path"],"exampleFix":"# before\nurl: \"nats://nats.example.com:4222\"\n# after\nurl: \"nats://nats.example.com:4222/litestream-backups\"","handlingStrategy":"validation","validationCode":"u, err := url.Parse(replicaURL)\nif err != nil || strings.Trim(u.Path, \"/\") == \"\" {\n\treturn fmt.Errorf(\"nats replica URL must include a bucket path: nats://host:port/<bucket>\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always include the bucket name in the NATS replica URL path","Validate config at startup (fail fast) before spawning replication","Keep a config template with an example nats URL including a bucket"],"tags":["nats","config","url"],"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"}