benbjohnson/litestream · error

cannot specify url & path for oss replica

Error message

cannot specify url & path for oss replica

What it means

newOSSReplicaClientFromConfig rejects configs that specify both `url` and `path` for an Alibaba Cloud OSS replica. These are two ways to describe the same location, and Litestream refuses the ambiguity rather than guessing precedence.

Source

Thrown at cmd/litestream/main.go:1992

	// Set connection options with defaults
	if c.MaxReconnects != nil {
		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
		)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Remove the `path` field and keep only `url`.
2. Or remove `url` and specify `bucket` + `path` (plus `region`/`endpoint`) as separate fields.
3. Derive the path from the URL and delete the redundant key.

Example fix

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

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

if err := runReplicate(); err != nil {
    if strings.Contains(err.Error(), "cannot specify url & path") {
        // strip the redundant field from config
    }
}

When it happens

Trigger: A replica config with `url: oss://bucket/prefix` AND `path: prefix` set at the same time.

Common situations: Adding a `path` field to an existing URL-based config when switching from full-URL to component-style configuration, or merging two config files.

Related errors

• cannot specify url & bucket 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/c5212a5b1a767fce. Report an issue: GitHub.