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.

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)

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: %w
• invalid scheme for NATS replica: %s
• heartbeat URL must be a valid HTTP or HTTPS URL
• failed to configure replica for %s: %w
• parse replica url: %w

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