What causes "oss: bucket name is required" in benbjohnson/litestream?

Set the bucket: add 'bucket: my-bucket' to the OSS replica config or set Bucket on oss.ReplicaClient before Init().

oss: bucket name is required

Error message

oss: bucket name is required

What it means

Litestream's OSS (Alibaba Cloud) replica client requires a bucket name to construct its SDK client. Init validates configuration eagerly and returns this error when Replica.Bucket is empty, before any network call is made. It is a fail-fast config validation, not a runtime/network failure.

Source

Thrown at oss/replica_client.go:123

}

// 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()

	if c.client != nil {
		return nil
	}

	// Validate required configuration
	if c.Bucket == "" {
		return fmt.Errorf("oss: bucket name is required")
	}

	// Use default region if not specified
	region := c.Region
	if region == "" {
		region = DefaultRegion
	}

	// Build configuration
	cfg := oss.LoadDefaultConfig()

	// Configure credentials
	if c.AccessKeyID != "" && c.AccessKeySecret != "" {
		cfg = cfg.WithCredentialsProvider(
			credentials.NewStaticCredentialsProvider(c.AccessKeyID, c.AccessKeySecret),
		)
	} else {
		// Use environment variable credentials provider

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set the bucket: add 'bucket: my-bucket' to the OSS replica config or set Bucket on oss.ReplicaClient before Init().
Use a full URL form: url: "oss://my-bucket.oss-cn-hangzhou.aliyuncs.com/path" so ParseHost extracts the bucket.
Verify the config file was actually loaded and env expansion ($VARS) produced a non-empty bucket; run 'litestream -config ... ' and inspect startup logs.
Check for typos (e.g. 'buckets' vs 'bucket') in the YAML replica section.

Example fix

// before
replicas:
  - type: oss
    region: cn-hangzhou
    path: db/ltx
// after
replicas:
  - type: oss
    bucket: my-litestream-bucket
    region: cn-hangzhou
    path: db/ltx

Defensive patterns

Strategy: validation

Validate before calling

if c.Bucket == "" {
    return fmt.Errorf("oss replica misconfigured: bucket is required")
}
if err := c.Init(ctx); err != nil { return err }

Prevention

Always set bucket (or a full oss://bucket... URL) in the replica config before starting litestream.
Lint the config with a schema check in CI; assert bucket is non-empty after env expansion.
Prefer full oss:// URLs so bucket/region are parsed in one place.

When it happens

Trigger: Calling Init() on an oss.ReplicaClient constructed with an empty Bucket field, or via a YAML config where the replica URL omits the bucket (e.g. url lacks the oss://bucket part or bucket was dropped during $PID/env expansion of the config).

Common situations: Missing 'bucket' key in litestream.yml; building the client programmatically with NewReplicaClientFromURL on a malformed URL like 'oss:///path'; env var interpolation silently yielding an empty bucket; copy-pasting an S3 config into an OSS replica block.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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