benbjohnson/litestream · error

bucket required for s3 replica URL

Error message

bucket required for s3 replica URL

What it means

Required-field guard in s3.NewReplicaClientFromURL: after parsing the replica URL (host, path, and query parameters), no bucket name was found. Fires when an s3:// URL lacks a bucket in its host portion, e.g. 's3:///path' or 's3://?endpoint=...'.

Source

Thrown at s3/replica_client.go:224

		return nil, err
	} else if ok {
		concurrency = int(v)
		concurrencySet = true
	}
	if v, ok, err := litestream.IntQueryValue(query, "partSize", "part-size"); err != nil {
		return nil, err
	} else if ok {
		partSize = v
	}
	if v := query.Get("storageClass"); v != "" {
		storageClass = v
	} else if v := query.Get("storage-class"); v != "" {
		storageClass = v
	}

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

	// Track if forcePathStyle was explicitly set via query parameter.
	forcePathStyleSet := query.Get("forcePathStyle") != "" || query.Get("force-path-style") != ""

	// Read authentication from environment variables
	if v := os.Getenv("AWS_ACCESS_KEY_ID"); v != "" {
		client.AccessKeyID = v
	} else if v := os.Getenv("LITESTREAM_ACCESS_KEY_ID"); v != "" {
		client.AccessKeyID = v
	}
	if v := os.Getenv("AWS_SECRET_ACCESS_KEY"); v != "" {
		client.SecretAccessKey = v
	} else if v := os.Getenv("LITESTREAM_SECRET_ACCESS_KEY"); v != "" {
		client.SecretAccessKey = v
	}

	if endpoint == "" {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Include the bucket in the URL host: s3://my-bucket/path

When it happens

Trigger: Thrown at s3/replica_client.go:224 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/30ed907c21440fba. Report an issue: GitHub.