{"record":{"id":"cf808b12bc586412","repo":"benbjohnson/litestream","slug":"failed-to-access-object-store-bucket-q-bucket-mu","errorCode":null,"errorMessage":"failed to access object store bucket %q (bucket must be created beforehand): %w","messagePattern":"failed to access object store bucket %q \\(bucket must be created beforehand\\): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nats/replica_client.go","lineNumber":228,"sourceCode":"\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 {\n\t\tc.nc.Close()\n\t\tc.nc = nil\n\t\tc.js = nil\n\t\tc.objectStore = nil\n\t}\n\treturn nil","sourceCodeStart":210,"sourceCodeEnd":246,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/nats/replica_client.go#L210-L246","documentation":"The NATS replica client intentionally never auto-creates buckets; it only opens an existing JetStream object store via js.ObjectStore(ctx, bucket). This error wraps a failed lookup, meaning the named bucket does not exist or the account cannot access it.","triggerScenarios":"Init → initObjectStore where c.js.ObjectStore returns bucket-not-found or a permission error: bucket never created on the NATS server, name mismatch, wrong server/account, or JetStream store deleted/lost.","commonSituations":"Provisioning litestream against a fresh NATS server without `nats object add`; bucket renamed; JetStream storage wiped (crash recovery); connecting with credentials for a different account that lacks access to the bucket.","solutions":["Create the bucket: `nats -s <server> object add <bucket>` (must be pre-created by design)","Verify the bucket exists: `nats object ls` and that the name matches the URL path exactly","Check account permissions/object-store limits if the bucket exists but access fails","If the JetStream store was lost, recreate the bucket and re-seed with a fresh full backup or `litestream reset`"],"exampleFix":"# before\n$ litestream replicate   # fails: bucket \"backups\" not found\n# after\n$ nats -s nats://host:4222 object add backups\n$ litestream replicate","handlingStrategy":"validation","validationCode":"// create-or-verify the bucket before Init\nbucket := \"backups\"\nif _, err := js.ObjectStore(ctx, bucket); err != nil {\n\tif _, err := js.CreateObjectStore(ctx, jetstream.ObjectStoreConfig{Bucket: bucket}); err != nil {\n\t\treturn fmt.Errorf(\"cannot create bucket %q: %w\", bucket, err)\n\t}\n}","typeGuard":null,"tryCatchPattern":"if err := client.Init(ctx); err != nil {\n\tvar nfErr interface{ Error() string }\n\tif strings.Contains(err.Error(), \"bucket must be created beforehand\") {\n\t\t// provision then re-init\n\t\treturn provisionBucket(ctx, bucket)\n\t}\n\t_ = nfErr\n\treturn err\n}","preventionTips":["Provision buckets (`nats object add`) in the same deploy step as litestream config","Use a dedicated litestream-only bucket to avoid cross-tool interference","Verify credentials have access to the bucket's account","Recreate the bucket after JetStream data loss and re-seed with a full backup"],"tags":["nats","jetstream","object-store","resource-not-found"],"backgroundTag":"resource-not-found","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"}