benbjohnson/litestream · error

s3: cannot lookup bucket region: %w

Error message

s3: cannot lookup bucket region: %w

What it means

Thrown during S3 replica client initialization when no Region and no Endpoint were configured, forcing an automatic bucket-region lookup against AWS (findBucketRegion). The lookup call itself failed — typically due to network/DNS failure, missing or invalid AWS credentials, a nonexistent bucket, or an STS/head-bucket denial — so the client cannot determine which regional endpoint to use. The underlying error is wrapped and identifies the exact cause.

Source

Thrown at s3/replica_client.go:377

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

	// Create HTTP client with 24 hour timeout for long-running operations
	httpClient := &http.Client{
		Timeout: 24 * time.Hour,
	}

	// Always configure custom HTTP Transport with controlled keepalive settings
	// to reduce idle CPU usage from default transport's aggressive keepalives.
	// See: https://github.com/benbjohnson/litestream/issues/992
	httpClient.Transport = &http.Transport{
		Proxy: http.ProxyFromEnvironment,
		DialContext: (&net.Dialer{
			Timeout:   30 * time.Second,

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Set the region explicitly in the replica configuration (region: us-east-1) to skip the automatic lookup
2. If using a non-AWS S3-compatible store (MinIO, GCS, etc.), set endpoint so DefaultRegion is used instead of a lookup
3. Verify AWS credentials are present and valid (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY or IAM role)
4. Check network connectivity and DNS resolution to s3.amazonaws.com
5. Confirm the bucket exists and the account is authorized to access it

When it happens

Trigger: Thrown at s3/replica_client.go:377 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/139039b051bae6c8. Report an issue: GitHub.