{"record":{"id":"5bdc94934f3f2f48","repo":"benbjohnson/litestream","slug":"bucket-name-is-required","errorCode":null,"errorMessage":"bucket name is required","messagePattern":"bucket name is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nats/replica_client.go","lineNumber":222,"sourceCode":"\t\topts = append(opts, nats.Secure())\n\t}\n\n\tif c.ClientCert != \"\" && c.ClientKey != \"\" {\n\t\topts = append(opts, nats.ClientCert(c.ClientCert, c.ClientKey))\n\t}\n\n\tif len(c.RootCAs) > 0 {\n\t\topts = append(opts, nats.RootCAs(c.RootCAs...))\n\t}\n\n\treturn opts\n}\n\n// initObjectStore retrieves the existing object store bucket.\n// The bucket must be pre-created using the NATS CLI or API.\nfunc (c *ReplicaClient) initObjectStore(ctx context.Context) error {\n\tif c.BucketName == \"\" {\n\t\treturn fmt.Errorf(\"bucket name is required\")\n\t}\n\n\t// Get existing object store - do not auto-create\n\tobjectStore, err := c.js.ObjectStore(ctx, c.BucketName)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to access object store bucket %q (bucket must be created beforehand): %w\", c.BucketName, err)\n\t}\n\n\tc.objectStore = objectStore\n\treturn nil\n}\n\n// Close closes the NATS connection.\nfunc (c *ReplicaClient) Close() error {\n\tc.mu.Lock()\n\tdefer c.mu.Unlock()\n\n\tif c.nc != nil {","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/nats/replica_client.go#L204-L240","documentation":"initObjectStore requires ReplicaClient.BucketName to be set before looking up the JetStream object store. This error means the bucket name is empty — the client was constructed (or a URL parsed) without a bucket, so litestream cannot locate the replica store.","triggerScenarios":"Init → initObjectStore with c.BucketName == \"\": usually reached when the URL-path check in NewReplicaClientFromURL was bypassed, e.g. constructing ReplicaClient directly in code or tests, or Path/URL fields mutated after construction.","commonSituations":"Building the NATS ReplicaClient programmatically without setting BucketName; custom config parsing that strips the URL path; tests constructing a bare &nats.ReplicaClient{} then calling Init.","solutions":["Set BucketName explicitly (or include the bucket in the replica URL path) before calling Init","If constructing manually, use NewReplicaClientFromURL so the bucket is parsed from the URL","Audit custom config loaders for code that trims or drops the URL path"],"exampleFix":"// before\nclient := &nats.ReplicaClient{}\nclient.BucketName = \"\"\n// after\nclient, err := nats.NewReplicaClientFromURL(\"nats://host:4222/backups\")","handlingStrategy":"validation","validationCode":"if client.BucketName == \"\" {\n\treturn fmt.Errorf(\"BucketName must be set (or use a nats:// URL whose path contains the bucket) before Init\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Construct the client via NewReplicaClientFromURL so the bucket is always parsed","Never build &nats.ReplicaClient{} literals without setting BucketName","Add startup config validation that every nats replica URL has a non-empty path"],"tags":["nats","config","object-store"],"backgroundTag":"empty-required-field","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"}