benbjohnson/litestream · error

cannot specify url & bucket for oss replica

Error message

cannot specify url & bucket for oss replica

What it means

Validation guard in newOSSReplicaClientFromConfig that rejects an Alibaba OSS replica config specifying both the full replica 'url' and the 'bucket' field, since the URL host already encodes bucket and region. Fires when ReplicaConfig.URL and ReplicaConfig.Bucket are both non-empty.

Source

Thrown at cmd/litestream/main.go:1994

		client.MaxReconnects = *c.MaxReconnects
	}
	if c.ReconnectWait != nil {
		client.ReconnectWait = *c.ReconnectWait
	}
	if c.Timeout != nil {
		client.Timeout = *c.Timeout
	}

	return client, nil
}

// newOSSReplicaClientFromConfig returns a new instance of oss.ReplicaClient built from config.
func newOSSReplicaClientFromConfig(c *ReplicaConfig, _ *litestream.Replica) (_ *oss.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 oss replica")
	} else if c.URL != "" && c.Bucket != "" {
		return nil, fmt.Errorf("cannot specify url & bucket for oss replica")
	}

	bucket, configPath := c.Bucket, c.Path
	region, endpoint := c.Region, c.Endpoint

	// Apply settings from URL, if specified.
	if c.URL != "" {
		_, host, upath, err := litestream.ParseReplicaURL(c.URL)
		if err != nil {
			return nil, err
		}

		var (
			ubucket string
			uregion string
		)

		ubucket, uregion, _ = oss.ParseHost(host)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Remove the `bucket` field and keep only `url`.
2. Or drop `url` and configure `bucket` (+ `path`, `region`, `endpoint`) as separate fields.
3. Search the replica block for leftover S3-era keys and delete them.

Example fix

# before
replicas:
  - url: oss://mybucket/backups
    bucket: mybucket
# after
replicas:
  - url: oss://mybucket/backups

// Reject ambiguous OSS config before invoking litestream
if cfg.URL != "" && cfg.Bucket != "" {
    return fmt.Errorf("oss replica: choose either url or bucket, not both")
}

if err := runReplicate(); err != nil {
    if strings.Contains(err.Error(), "cannot specify url & bucket") {
        // remove bucket or url from config
    }
}

When it happens

Trigger: A replica config containing both `url: oss://mybucket/prefix` and `bucket: mybucket`.

Common situations: Porting an S3-style config (which allows both forms) to OSS; adding a URL while leaving the old `bucket` key in place.

Related errors

• cannot specify url & path for oss replica
• bucket required for oss replica
• oss: bucket name is required
• oss: invalid url scheme
• heartbeat URL must be a valid HTTP or HTTPS URL

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