benbjohnson/litestream · error

bucket required for nats replica URL

Error message

bucket required for nats replica URL

What it means

NewReplicaClientFromURL parses a NATS replica URL (nats://user:pass@host:port/bucket) and requires the URL path to name the JetStream object-store bucket. This error is returned when the URL has no path component, because the client cannot know which bucket to store LTX files in.

Solutions

1. Append the bucket name to the URL path: `nats://host:4222/mybucket`
2. Pre-create the bucket with the NATS CLI (`nats object add mybucket`) and use the same name in the URL
3. Check the resolved config/env value — a truncated URL may drop the path

Example fix

# before
url: "nats://nats.example.com:4222"
# after
url: "nats://nats.example.com:4222/litestream-backups"

u, err := url.Parse(replicaURL)
if err != nil || strings.Trim(u.Path, "/") == "" {
	return fmt.Errorf("nats replica URL must include a bucket path: nats://host:port/<bucket>")
}

When it happens

Trigger: Configuring a replica URL like `nats://localhost:4222` or `nats://localhost:4222/` with an empty path, then calling NewReplicaClientFromURL (directly or via litestream config loading).

Common situations: Copy-pasting a plain NATS server address into the litestream config `url` field; forgetting the bucket suffix when migrating from S3-style URLs; env var expansion producing an empty path.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• invalid NATS URL
• invalid scheme for NATS replica
• bucket name is required
• bucket required for gs replica URL
• bucket required for NATS replica

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

Appendix: source

Thrown at nats/replica_client.go:116

// URL format: nats://[user:pass@]host[:port]/bucket
func NewReplicaClientFromURL(scheme, host, urlPath string, query url.Values, userinfo *url.Userinfo) (litestream.ReplicaClient, error) {
	client := NewReplicaClient()

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

	// Extract credentials from userinfo if present
	if userinfo != nil {
		client.Username = userinfo.Username()
		client.Password, _ = userinfo.Password()
	}

	// Extract bucket name from path
	bucket := strings.Trim(urlPath, "/")
	if bucket == "" {
		return nil, fmt.Errorf("bucket required for nats replica URL")
	}
	client.BucketName = bucket

	return client, nil
}

// Type returns "nats" as the client type.
func (c *ReplicaClient) Type() string {
	return ReplicaClientType
}

// 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

View on GitHub (pinned to 4ed7a308f6)