benbjohnson/litestream · error

bucket required for NATS replica

Error message

bucket required for NATS replica

What it means

newReplicaClientFromConfig validates NATS replica configuration before building the client. The bucket (the NATS object-store bucket Litestream reads/writes) was resolved from both the URL and the config's `bucket` field and both were empty, so replication cannot proceed.

Source

Thrown at cmd/litestream/main.go:1943

		// Reconstruct URL without bucket path
		if host != "" {
			url = fmt.Sprintf("nats://%s", host)
		}

		// Extract bucket name from path
		if bucketPath != "" {
			bucket = strings.Trim(bucketPath, "/")
		}
	}

	// Use bucket from config if not extracted from URL
	if bucket == "" {
		bucket = c.Bucket
	}

	// Ensure required settings are set
	if bucket == "" {
		return nil, fmt.Errorf("bucket required for NATS replica")
	}

	// Validate TLS configuration
	// Both client cert and key must be specified together
	if (c.ClientCert != "") != (c.ClientKey != "") {
		return nil, fmt.Errorf("client-cert and client-key must both be specified for mutual TLS authentication")
	}

	// Build replica client
	client := nats.NewReplicaClient()
	client.URL = url
	client.BucketName = bucket

	// Set authentication options
	client.JWT = c.JWT
	client.Seed = c.Seed
	client.Creds = c.Creds
	client.NKey = c.NKey

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Add `bucket: <name>` to the NATS replica config block.
2. Include the bucket in the URL path, e.g. `nats://localhost:4222/mybucket`.
3. If using YAML keys, confirm the field is spelled `bucket` and is under the replica section.

Example fix

# before
replicas:
  - url: nats://localhost:4222
# after
replicas:
  - url: nats://localhost:4222
    bucket: litestream-db

// Go: before calling replicate, validate the replica config
if u.Scheme == "nats" && cfg.Bucket == "" && path.Clean(u.Path) == "/" || path.Base(u.Path) == "." || path.Base(u.Path) == "/" {
    return fmt.Errorf("nats replica needs bucket: set bucket: in config or nats://host/bucket")
}

if err := runReplicate(); err != nil {
    if strings.Contains(err.Error(), "bucket required") {
        // prompt/fix config: add bucket field
    }
}

When it happens

Trigger: Running `litestream replicate` with a replica whose `url` is a nats:// URL without a bucket path component and no `bucket:` field set in the replica config.

Common situations: Copy-pasting a NATS URL like `nats://localhost:4222` without a bucket suffix; migrating configs from S3 (where bucket is in the URL) and forgetting NATS also needs an explicit bucket name.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• bucket required for oss replica
• database config #%d: 'pattern' is required when using 'dir'
• must specify replica for database
• cannot specify 'replica' and 'replicas' on a database
• multiple replicas on a single database are no longer support

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