{"record":{"id":"b78c418ae4231041","repo":"benbjohnson/litestream","slug":"nats-failed-to-initialize-object-store-w","errorCode":null,"errorMessage":"nats: failed to initialize object store: %w","messagePattern":"nats: failed to initialize object store: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"nats/replica_client.go","lineNumber":144,"sourceCode":"}\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\n\t}\n\n\tif c.nc == nil {\n\t\tif err := c.connect(ctx); err != nil {\n\t\t\treturn fmt.Errorf(\"nats: failed to connect: %w\", err)\n\t\t}\n\t}\n\n\tif err := c.initObjectStore(ctx); err != nil {\n\t\treturn fmt.Errorf(\"nats: failed to initialize object store: %w\", err)\n\t}\n\n\treturn nil\n}\n\n// connect establishes a connection to NATS server with proper configuration.\nfunc (c *ReplicaClient) connect(_ context.Context) error {\n\turl := c.URL\n\tif url == \"\" {\n\t\turl = nats.DefaultURL\n\t}\n\n\tnc, err := nats.Connect(url, c.options()...)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to connect to NATS server: %w\", err)\n\t}\n\n\tjs, err := jetstream.New(nc)","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/nats/replica_client.go#L126-L162","documentation":"ReplicaClient.Init wraps failures from initObjectStore() with this prefix. It means the NATS connection succeeded but retrieving the JetStream object store bucket failed — usually because the bucket does not exist, the name is empty, or JetStream is unavailable.","triggerScenarios":"Init called when c.objectStore == nil and c.js.ObjectStore(ctx, bucket) returns an error: bucket never created, wrong bucket name, insufficient account permissions, or JetStream disabled on the server.","commonSituations":"Fresh NATS install where the bucket was never created; typo in the bucket name in the URL path; JetStream disabled server-side; account limits (max_objectstore buckets) exceeded.","solutions":["Create the bucket beforehand: `nats object add <bucket>` — this client does not auto-create buckets","Confirm the bucket name in the replica URL matches the created bucket exactly","Check the inner wrapped error for the specific object-store failure","Ensure JetStream is enabled on the NATS server (`jetstream: {enabled: true}` in nats-server config)"],"exampleFix":"# before: bucket missing -> Init fails\nurl: \"nats://host:4222/backups\"\n# after\n$ nats -s nats://host:4222 object add backups\nurl: \"nats://host:4222/backups\"","handlingStrategy":"validation","validationCode":"// ensure the bucket exists before Init\nif out, err := exec.Command(\"nats\", \"-s\", natsURL, \"object\", \"ls\").Output(); err != nil || !strings.Contains(string(out), bucket) {\n\treturn fmt.Errorf(\"bucket %q missing; run: nats object add %s\", bucket, bucket)\n}","typeGuard":null,"tryCatchPattern":"if err := client.Init(ctx); err != nil {\n\tif strings.Contains(err.Error(), \"failed to initialize object store\") {\n\t\treturn fmt.Errorf(\"create the bucket first (nats object add); JetStream/bucket error: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Pre-create JetStream object-store buckets in provisioning scripts","Enable JetStream on the NATS server before configuring litestream","Verify bucket names match exactly between `nats object add` and the litestream URL"],"tags":["nats","jetstream","object-store","config"],"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"}