benbjohnson/litestream · error

bucket name is required

Error message

bucket name is required

What it means

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.

Source

Thrown at nats/replica_client.go:222

		opts = append(opts, nats.Secure())
	}

	if c.ClientCert != "" && c.ClientKey != "" {
		opts = append(opts, nats.ClientCert(c.ClientCert, c.ClientKey))
	}

	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 {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Set BucketName explicitly (or include the bucket in the replica URL path) before calling Init
2. If constructing manually, use NewReplicaClientFromURL so the bucket is parsed from the URL
3. Audit custom config loaders for code that trims or drops the URL path

Example fix

// before
client := &nats.ReplicaClient{}
client.BucketName = ""
// after
client, err := nats.NewReplicaClientFromURL("nats://host:4222/backups")

if client.BucketName == "" {
	return fmt.Errorf("BucketName must be set (or use a nats:// URL whose path contains the bucket) before Init")
}

When it happens

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

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

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• nats: failed to initialize object store: %w
• invalid NATS URL: %w
• invalid scheme for NATS replica: %s
• bucket required for NATS replica
• client-cert and client-key must both be specified for mutual

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