benbjohnson/litestream · error

bucket required for abs replica URL

Error message

bucket required for abs replica URL

What it means

NewReplicaClientFromURL parses an ABS (Azure Blob Storage) replica URL and requires a bucket (container) component in the URL host. When the URL has no container name, parsing cannot produce a usable client and this error is returned.

Source

Thrown at abs/replica_client.go:88

	c.logger = logger.WithGroup(ReplicaClientType)
}

// NewReplicaClientFromURL creates a new ReplicaClient from URL components.
// This is used by the replica client factory registration.
// URL format: abs://[account-name@]container/path
func NewReplicaClientFromURL(scheme, host, urlPath string, query url.Values, userinfo *url.Userinfo) (litestream.ReplicaClient, error) {
	client := NewReplicaClient()

	// Extract account name from userinfo if present (abs://account@container/path)
	if userinfo != nil {
		client.AccountName = userinfo.Username()
	}

	client.Bucket = host
	client.Path = urlPath

	if client.Bucket == "" {
		return nil, fmt.Errorf("bucket required for abs replica URL")
	}

	return client, nil
}

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

// Init initializes the connection to Azure. No-op if already initialized.
func (c *ReplicaClient) Init(ctx context.Context) (err error) {
	c.mu.Lock()
	defer c.mu.Unlock()

	if c.client != nil {
		return nil
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Include the container name in the URL host: abs://mycontainer/path/to/replica
2. Re-check the replica URL in the config file for typos or a missing container segment
3. Print/validate the parsed URL (scheme, host, path) before passing it to NewReplicaClientFromURL

Example fix

// before
client, err := abs.NewReplicaClientFromURL("abs:///backups/db")
// after
client, err := abs.NewReplicaClientFromURL("abs://mycontainer/backups/db")

u, _ := url.Parse(replicaURL)
if u.Scheme == "abs" && u.Host == "" {
    return fmt.Errorf("abs URL %q missing container (bucket) host", replicaURL)
}

When it happens

Trigger: Calling NewReplicaClientFromURL with an abs:// URL missing the host portion, e.g. 'abs:///some/path' or an empty/malformed URL where host (container) resolves to ''.

Common situations: Hand-edited config with an incomplete replica URL; copying a container-relative path instead of the full abs://container/path URL; YAML quoting stripping the host; automation templating leaving the container blank.

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

• abs: container name is required
• abs: account name is required when endpoint is not specified
• abs: cannot create azure blob client with SAS token: %w
• abs: cannot create shared key credential: %w
• abs: cannot create azure blob client with shared key: %w

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