benbjohnson/litestream · error

bucket required for s3 replica

Error message

bucket required for s3 replica

What it means

After merging URL components and discrete fields, no bucket could be determined for the S3 replica. The bucket is the only mandatory S3 setting; it is missing from both the URL host and the bucket field.

Source

Thrown at cmd/litestream/main.go:1605

			storageClass = ustorageClass
		}
		if !forcePathStyle {
			forcePathStyle = uforcePathStyle
		}
		if !signSetting.set && usignPayloadSet {
			signSetting.Set(usignPayload)
		}
		if !signAcceptEncodingSetting.set && usignAcceptEncodingSet {
			signAcceptEncodingSetting.Set(usignAcceptEncoding)
		}
		if !requireSetting.set && urequireContentMD5Set {
			requireSetting.Set(urequireContentMD5)
		}
	}

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

	// Detect S3-compatible provider endpoints for applying appropriate defaults.
	// These providers require specific settings to work correctly with AWS SDK v2.
	isHetzner := litestream.IsHetznerEndpoint(endpoint)
	isTigris := litestream.IsTigrisEndpoint(endpoint)
	if !isTigris && !endpointWasSet && litestream.IsTigrisEndpoint(c.Endpoint) {
		isTigris = true
	}
	isDigitalOcean := litestream.IsDigitalOceanEndpoint(endpoint)
	isBackblaze := litestream.IsBackblazeEndpoint(endpoint)
	isFilebase := litestream.IsFilebaseEndpoint(endpoint)
	isScaleway := litestream.IsScalewayEndpoint(endpoint)
	isMinIO := litestream.IsMinIOEndpoint(endpoint)
	isCloudflareR2 := litestream.IsCloudflareR2Endpoint(endpoint)
	isSupabase := litestream.IsSupabaseEndpoint(endpoint)

	// Track if forcePathStyle was explicitly set by user (config or URL query param).

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Set bucket in the replica config
2. Or use a url like s3://my-bucket/path so the host supplies the bucket

When it happens

Trigger: Thrown at cmd/litestream/main.go:1605 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/8b326265f955e941. Report an issue: GitHub.