benbjohnson/litestream · error

cannot specify url & bucket for s3 replica

Error message

cannot specify url & bucket for s3 replica

What it means

Validation guard in NewS3ReplicaClientFromConfig that rejects an S3 replica config specifying both the full replica 'url' and the 'bucket' field. The URL already encodes the bucket in its host portion, so both being set is contradictory configuration. Fires when ReplicaConfig.URL and ReplicaConfig.Bucket are both non-empty.

Source

Thrown at cmd/litestream/main.go:1458

	// Expand home prefix and return absolute path.
	if configPath, err = expand(configPath); err != nil {
		return nil, err
	}

	// Instantiate replica and apply time fields, if set.
	client := file.NewReplicaClient(configPath)
	client.Replica = r
	return client, nil
}

// NewS3ReplicaClientFromConfig returns a new instance of s3.ReplicaClient built from config.
// Exported for testing.
func NewS3ReplicaClientFromConfig(c *ReplicaConfig, _ *litestream.Replica) (_ *s3.ReplicaClient, err error) {
	// Ensure URL & constituent parts are not both specified.
	if c.URL != "" && c.Path != "" {
		return nil, fmt.Errorf("cannot specify url & path for s3 replica")
	} else if c.URL != "" && c.Bucket != "" {
		return nil, fmt.Errorf("cannot specify url & bucket for s3 replica")
	}

	bucket, configPath := c.Bucket, c.Path
	region, endpoint, skipVerify := c.Region, c.Endpoint, c.SkipVerify
	storageClass := c.StorageClass
	signSetting := newBoolSetting(true)
	if v := c.SignPayload; v != nil {
		signSetting.Set(*v)
	}
	signAcceptEncodingSetting := newBoolSetting(true)
	if v := c.SignAcceptEncoding; v != nil {
		signAcceptEncodingSetting.Set(*v)
	}
	requireSetting := newBoolSetting(true)
	if v := c.RequireContentMD5; v != nil {
		requireSetting.Set(*v)
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Drop the url and keep bucket/path fields, or drop bucket and keep the s3://bucket/path url

When it happens

Trigger: Thrown at cmd/litestream/main.go:1458 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/04db30aa9a9a6ac5. Report an issue: GitHub.