benbjohnson/litestream · error

failed to access object store bucket %q (bucket must be crea

Error message

failed to access object store bucket %q (bucket must be created beforehand): %w

What it means

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.

Source

Thrown at nats/replica_client.go:228

	if len(c.RootCAs) > 0 {
		opts = append(opts, nats.RootCAs(c.RootCAs...))
	}

	return opts
}

// initObjectStore retrieves the existing object store bucket.
// The bucket must be pre-created using the NATS CLI or API.
func (c *ReplicaClient) initObjectStore(ctx context.Context) error {
	if c.BucketName == "" {
		return fmt.Errorf("bucket name is required")
	}

	// Get existing object store - do not auto-create
	objectStore, err := c.js.ObjectStore(ctx, c.BucketName)
	if err != nil {
		return fmt.Errorf("failed to access object store bucket %q (bucket must be created beforehand): %w", c.BucketName, err)
	}

	c.objectStore = objectStore
	return nil
}

// Close closes the NATS connection.
func (c *ReplicaClient) Close() error {
	c.mu.Lock()
	defer c.mu.Unlock()

	if c.nc != nil {
		c.nc.Close()
		c.nc = nil
		c.js = nil
		c.objectStore = nil
	}
	return nil

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Create the bucket: `nats -s <server> object add <bucket>` (must be pre-created by design)
2. Verify the bucket exists: `nats object ls` and that the name matches the URL path exactly
3. Check account permissions/object-store limits if the bucket exists but access fails
4. If the JetStream store was lost, recreate the bucket and re-seed with a fresh full backup or `litestream reset`

Example fix

# before
$ litestream replicate   # fails: bucket "backups" not found
# after
$ nats -s nats://host:4222 object add backups
$ litestream replicate

// create-or-verify the bucket before Init
bucket := "backups"
if _, err := js.ObjectStore(ctx, bucket); err != nil {
	if _, err := js.CreateObjectStore(ctx, jetstream.ObjectStoreConfig{Bucket: bucket}); err != nil {
		return fmt.Errorf("cannot create bucket %q: %w", bucket, err)
	}
}

if err := client.Init(ctx); err != nil {
	var nfErr interface{ Error() string }
	if strings.Contains(err.Error(), "bucket must be created beforehand") {
		// provision then re-init
		return provisionBucket(ctx, bucket)
	}
	_ = nfErr
	return err
}

When it happens

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

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

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

• nats: failed to initialize object store: %w
• failed to create JetStream context: %w
• bucket name is required
• 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/cf808b12bc586412. Report an issue: GitHub.