benbjohnson/litestream · error

s3: bucket name is required

Error message

s3: bucket name is required

What it means

Configuration validation in the S3 replica client's Init: the client was initialized without a Bucket set. Fires on first use of a client built programmatically (not via URL/config parsing) when the Bucket field was never assigned, making any S3 operation impossible.

Source

Thrown at s3/replica_client.go:362

}

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

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

	if c.s3 != nil {
		return nil
	}

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

	// Validate SSE configuration
	if err := c.validateSSEConfig(); err != nil {
		return err
	}

	// Look up region if not specified and no endpoint is used.
	// Endpoints are typically used for non-S3 object stores and do not
	// necessarily require a region.
	region := c.Region
	if region == "" {
		if c.Endpoint == "" {
			if region, err = c.findBucketRegion(ctx, c.Bucket); err != nil {
				return fmt.Errorf("s3: cannot lookup bucket region: %w", err)
			}
		} else {
			region = DefaultRegion // default for non-S3 object stores

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Set the bucket in the replica config or URL

When it happens

Trigger: Thrown at s3/replica_client.go:362 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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