benbjohnson/litestream · error

abs: account name is required when endpoint is not specified

Error message

abs: account name is required when endpoint is not specified

What it means

When no explicit Endpoint is configured, Init derives the Azure Blob endpoint from the AccountName (https://<account>.blob.core.windows.net). If neither Endpoint nor AccountName is set, it cannot build an endpoint and returns this error.

Source

Thrown at abs/replica_client.go:117

// 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,
				TryTimeout:    15 * time.Minute, // Reasonable timeout for blob operations
				StatusCodes: []int{
					http.StatusRequestTimeout,
					http.StatusTooManyRequests,
					http.StatusInternalServerError,
					http.StatusBadGateway,
					http.StatusServiceUnavailable,

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Set account-name: <storage-account> in the abs replica config (or c.AccountName) so the default endpoint can be derived
2. Alternatively set endpoint: https://<account>.blob.core.windows.net (or a custom endpoint) explicitly
3. Verify with a minimal config that Init no longer reports the error before adding back optional fields

Example fix

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

if c.Endpoint == "" && c.AccountName == "" {
    return errors.New("abs replica requires endpoint or account-name")
}

When it happens

Trigger: Calling Init with c.Endpoint == "" and c.AccountName == "" — typically a config block that provides only a container name and credentials, or omits account details entirely.

Common situations: Using a custom endpoint but misspelling the key so it is never read; assuming account name can be inferred from credentials (it cannot); Azure Government/China users who must set endpoint explicitly and forgot the account-name too.

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

• bucket required for abs replica URL
• abs: container name is required
• abs: cannot create azure blob client with shared key: %w
• abs: cannot create azure blob client with SAS token: %w
• abs: cannot create shared key credential: %w

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