benbjohnson/litestream · error

abs: container name is required

Error message

abs: container name is required

What it means

ReplicaClient.Init validates required ABS configuration before constructing the Azure blob client; the Bucket field holds the Azure container name. An empty Bucket means no container was configured, so the client cannot address any storage and Init fails with this error.

Source

Thrown at abs/replica_client.go:110

}

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

	// Validate required configuration
	if c.Bucket == "" {
		return fmt.Errorf("abs: container name is required")
	}

	// Construct & parse endpoint unless already set.
	endpoint := c.Endpoint
	if endpoint == "" {
		if c.AccountName == "" {
			return fmt.Errorf("abs: account name is required when endpoint is not specified")
		}
		endpoint = fmt.Sprintf("https://%s.blob.core.windows.net", c.AccountName)
	}

	// Configure client options with retry policy
	clientOptions := &azblob.ClientOptions{
		ClientOptions: azcore.ClientOptions{
			Retry: policy.RetryOptions{
				MaxRetries:    10,
				RetryDelay:    time.Second,
				MaxRetryDelay: 30 * time.Second,

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Set the container name: either add bucket: mycontainer to the abs replica config block or set client.Bucket before Init
2. Re-run litestream with the corrected config and confirm via logs that Init succeeds
3. Validate the parsed ReplicaClient struct (Bucket != "") in tests/automation before calling Init

Example fix

// before (config)
replica:
  type: abs
  account-name: myaccount
// after
replica:
  type: abs
  bucket: mycontainer
  account-name: myaccount

if c.Bucket == "" {
    return errors.New("abs replica config missing bucket (container) before Init")
}

When it happens

Trigger: Calling Init on an abs.ReplicaClient whose Bucket field is empty — e.g. a YAML config block for the ABS replica that lacks the 'bucket' key, or a client constructed programmatically without setting Bucket.

Common situations: Config file missing the bucket/container field for the abs replica; renaming the key in YAML so litestream reads an empty value; building the client in code and forgetting client.Bucket = ... before Init.

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

• bucket required for abs replica URL
• 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/e4d79640320a336f. Report an issue: GitHub.