What causes "bucket required for abs replica" in benbjohnson/litestream?

Set 'bucket: ' in the abs replica config block

bucket required for abs replica

Error message

bucket required for abs replica

What it means

Thrown by newABSReplicaClientFromConfig in cmd/litestream/main.go after config parsing: the Azure Blob Storage replica client requires a container (stored in client.Bucket). The bucket is normally taken from c.Bucket or derived from the URL host; if neither yields a non-empty value, startup of this replica fails because ABS cannot address any storage container.

Source

Thrown at cmd/litestream/main.go:1795

		u, err := url.Parse(c.URL)
		if err != nil {
			return nil, err
		}

		if client.AccountName == "" && u.User != nil {
			client.AccountName = u.User.Username()
		}
		if client.Bucket == "" {
			client.Bucket = u.Host
		}
		if client.Path == "" {
			client.Path = strings.TrimPrefix(path.Clean(u.Path), "/")
		}
	}

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

	return client, nil
}

// newSFTPReplicaClientFromConfig returns a new instance of sftp.ReplicaClient built from config.
func newSFTPReplicaClientFromConfig(c *ReplicaConfig, _ *litestream.Replica) (_ *sftp.ReplicaClient, err error) {
	// Ensure URL & constituent parts are not both specified.
	if c.URL != "" && c.Path != "" {
		return nil, fmt.Errorf("cannot specify url & path for sftp replica")
	} else if c.URL != "" && c.Host != "" {
		return nil, fmt.Errorf("cannot specify url & host for sftp replica")
	}

	host, user, password, path := c.Host, c.User, c.Password, c.Path

	// Apply settings from URL, if specified.
	if c.URL != "" {

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set 'bucket: <container-name>' in the abs replica config block
Or set 'url: azure://<container>/<path>' so the bucket is derived from the URL host
Verify with 'litestream -config <file> test' style validation that the YAML key names are correct

Example fix

# before
replicas:
  - type: abs
    path: db/replica
# after
replicas:
  - type: abs
    bucket: my-container
    path: db/replica

Defensive patterns

Strategy: validation

Validate before calling

// before loading config in Go
if rep.Type == "abs" {
    u, _ := url.Parse(rep.URL)
    if rep.Bucket == "" && (rep.URL == "" || u.Host == "") {
        return fmt.Errorf("abs replica %s: set bucket or a url with a host", rep.Name)
    }
}

Type guard

func absBucketConfigured(c *ReplicaConfig) bool {
    if c.Bucket != "" { return true }
    if c.URL == "" { return false }
    u, err := url.Parse(c.URL)
    return err == nil && u.Host != ""
}

Prevention

Always set 'bucket:' for abs replicas even when using url
Validate config with a startup dry-run before deploying
Pin YAML key names (bucket, not container) in your config templates

When it happens

Trigger: An 'abs' replica is configured where neither replica.bucket nor replica.url is set (or url has an empty host, e.g. 'azure://'), so client.Bucket remains empty after URL application.

Common situations: YAML typo like 'containers:' instead of 'bucket:', forgetting the replica url while migrating from per-field config, or an env-expanded url that expanded to an empty/invalid string.

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

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