{"record":{"id":"03ec8e0171f726a8","repo":"benbjohnson/litestream","slug":"bucket-required-for-nats-replica","errorCode":null,"errorMessage":"bucket required for NATS replica","messagePattern":"bucket required for NATS replica","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/main.go","lineNumber":1943,"sourceCode":"\t\t// Reconstruct URL without bucket path\n\t\tif host != \"\" {\n\t\t\turl = fmt.Sprintf(\"nats://%s\", host)\n\t\t}\n\n\t\t// Extract bucket name from path\n\t\tif bucketPath != \"\" {\n\t\t\tbucket = strings.Trim(bucketPath, \"/\")\n\t\t}\n\t}\n\n\t// Use bucket from config if not extracted from URL\n\tif bucket == \"\" {\n\t\tbucket = c.Bucket\n\t}\n\n\t// Ensure required settings are set\n\tif bucket == \"\" {\n\t\treturn nil, fmt.Errorf(\"bucket required for NATS replica\")\n\t}\n\n\t// Validate TLS configuration\n\t// Both client cert and key must be specified together\n\tif (c.ClientCert != \"\") != (c.ClientKey != \"\") {\n\t\treturn nil, fmt.Errorf(\"client-cert and client-key must both be specified for mutual TLS authentication\")\n\t}\n\n\t// Build replica client\n\tclient := nats.NewReplicaClient()\n\tclient.URL = url\n\tclient.BucketName = bucket\n\n\t// Set authentication options\n\tclient.JWT = c.JWT\n\tclient.Seed = c.Seed\n\tclient.Creds = c.Creds\n\tclient.NKey = c.NKey","sourceCodeStart":1925,"sourceCodeEnd":1961,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/main.go#L1925-L1961","documentation":"newReplicaClientFromConfig validates NATS replica configuration before building the client. The bucket (the NATS object-store bucket Litestream reads/writes) was resolved from both the URL and the config's `bucket` field and both were empty, so replication cannot proceed.","triggerScenarios":"Running `litestream replicate` with a replica whose `url` is a nats:// URL without a bucket path component and no `bucket:` field set in the replica config.","commonSituations":"Copy-pasting a NATS URL like `nats://localhost:4222` without a bucket suffix; migrating configs from S3 (where bucket is in the URL) and forgetting NATS also needs an explicit bucket name.","solutions":["Add `bucket: <name>` to the NATS replica config block.","Include the bucket in the URL path, e.g. `nats://localhost:4222/mybucket`.","If using YAML keys, confirm the field is spelled `bucket` and is under the replica section."],"exampleFix":"# before\nreplicas:\n  - url: nats://localhost:4222\n# after\nreplicas:\n  - url: nats://localhost:4222\n    bucket: litestream-db","handlingStrategy":"validation","validationCode":"// Go: before calling replicate, validate the replica config\nif u.Scheme == \"nats\" && cfg.Bucket == \"\" && path.Clean(u.Path) == \"/\" || path.Base(u.Path) == \".\" || path.Base(u.Path) == \"/\" {\n    return fmt.Errorf(\"nats replica needs bucket: set bucket: in config or nats://host/bucket\")\n}","typeGuard":null,"tryCatchPattern":"if err := runReplicate(); err != nil {\n    if strings.Contains(err.Error(), \"bucket required\") {\n        // prompt/fix config: add bucket field\n    }\n}","preventionTips":["Always include the bucket in a nats:// URL or set the bucket key explicitly.","Lint your litestream.yml with `litestream replicate -config ... -no-banner` in CI before deploy."],"tags":["nats","config","replica","missing-field"],"backgroundTag":"missing-required-config-field","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"}