benbjohnson/litestream · error

nats: failed to initialize object store: %w

Error message

nats: failed to initialize object store: %w

What it means

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.

Source

Thrown at nats/replica_client.go:144

}

// Init initializes the connection to NATS JetStream. No-op if already initialized.
func (c *ReplicaClient) Init(ctx context.Context) error {
	c.mu.Lock()
	defer c.mu.Unlock()

	if c.objectStore != nil {
		return nil
	}

	if c.nc == nil {
		if err := c.connect(ctx); err != nil {
			return fmt.Errorf("nats: failed to connect: %w", err)
		}
	}

	if err := c.initObjectStore(ctx); err != nil {
		return fmt.Errorf("nats: failed to initialize object store: %w", err)
	}

	return nil
}

// connect establishes a connection to NATS server with proper configuration.
func (c *ReplicaClient) connect(_ context.Context) error {
	url := c.URL
	if url == "" {
		url = nats.DefaultURL
	}

	nc, err := nats.Connect(url, c.options()...)
	if err != nil {
		return fmt.Errorf("failed to connect to NATS server: %w", err)
	}

	js, err := jetstream.New(nc)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Create the bucket beforehand: `nats object add <bucket>` — this client does not auto-create buckets
2. Confirm the bucket name in the replica URL matches the created bucket exactly
3. Check the inner wrapped error for the specific object-store failure
4. Ensure JetStream is enabled on the NATS server (`jetstream: {enabled: true}` in nats-server config)

Example fix

# before: bucket missing -> Init fails
url: "nats://host:4222/backups"
# after
$ nats -s nats://host:4222 object add backups
url: "nats://host:4222/backups"

// ensure the bucket exists before Init
if out, err := exec.Command("nats", "-s", natsURL, "object", "ls").Output(); err != nil || !strings.Contains(string(out), bucket) {
	return fmt.Errorf("bucket %q missing; run: nats object add %s", bucket, bucket)
}

if err := client.Init(ctx); err != nil {
	if strings.Contains(err.Error(), "failed to initialize object store") {
		return fmt.Errorf("create the bucket first (nats object add); JetStream/bucket error: %w", err)
	}
	return err
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• failed to create JetStream context: %w
• bucket name is required
• failed to access object store bucket %q (bucket must be crea
• invalid NATS URL: %w
• invalid scheme for NATS replica: %s

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/b78c418ae4231041. Report an issue: GitHub.