benbjohnson/litestream · error

bucket required for oss replica URL

Error message

bucket required for oss replica URL

What it means

NewReplicaClientFromURL for OSS found no bucket: the oss:// URL host was empty or did not resolve to a bucket (expected format oss://bucket[.oss-region.aliyuncs.com]/path). The bucket is mandatory for replication.

Source

Thrown at oss/replica_client.go:97

func NewReplicaClient() *ReplicaClient {
	return &ReplicaClient{
		logger: slog.Default().WithGroup(ReplicaClientType),
	}
}

func (c *ReplicaClient) SetLogger(logger *slog.Logger) {
	c.logger = logger.WithGroup(ReplicaClientType)
}

// NewReplicaClientFromURL creates a new ReplicaClient from URL components.
// This is used by the replica client factory registration.
// URL format: oss://bucket[.oss-region.aliyuncs.com]/path
func NewReplicaClientFromURL(scheme, host, urlPath string, query url.Values, userinfo *url.Userinfo) (litestream.ReplicaClient, error) {
	client := NewReplicaClient()

	bucket, region, _ := ParseHost(host)
	if bucket == "" {
		return nil, fmt.Errorf("bucket required for oss replica URL")
	}

	client.Bucket = bucket
	client.Region = region
	client.Path = urlPath

	return client, nil
}

// Type returns "oss" as the client type.
func (c *ReplicaClient) Type() string {
	return ReplicaClientType
}

// Init initializes the connection to OSS. No-op if already initialized.
func (c *ReplicaClient) Init(ctx context.Context) (err error) {
	c.mu.Lock()
	defer c.mu.Unlock()

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Fix the URL to include the bucket host, e.g. oss://my-bucket.oss-cn-hangzhou.aliyuncs.com/path

When it happens

Trigger: Thrown at oss/replica_client.go:97 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/6a9888abef568356. Report an issue: GitHub.