What causes "bucket required for oss replica" in benbjohnson/litestream?

Add `bucket: ` to the OSS replica config.

bucket required for oss replica

Error message

bucket required for oss replica

What it means

After resolving the bucket from either the URL or the `bucket` config field, newOSSReplicaClientFromConfig found neither set. An OSS replica cannot determine which bucket to use, so client construction fails.

Source

Thrown at cmd/litestream/main.go:2028

		)

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

		// Only apply URL parts to fields that have not been overridden.
		if configPath == "" {
			configPath = upath
		}
		if bucket == "" {
			bucket = ubucket
		}
		if region == "" {
			region = uregion
		}
	}

	// Ensure required settings are set.
	if bucket == "" {
		return nil, fmt.Errorf("bucket required for oss replica")
	}

	// Build replica client.
	client := oss.NewReplicaClient()
	client.AccessKeyID = c.AccessKeyID
	client.AccessKeySecret = c.SecretAccessKey
	client.Bucket = bucket
	client.Path = configPath
	client.Region = region
	client.Endpoint = endpoint

	// Apply upload configuration if specified.
	if c.PartSize != nil {
		client.PartSize = int64(*c.PartSize)
	}
	if c.Concurrency != nil {
		client.Concurrency = *c.Concurrency
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

Add `bucket: <name>` to the OSS replica config.
Use a full URL form: `url: oss://<bucket>/<path>`.
Verify the environment variable feeding the bucket expands to a non-empty value.

Example fix

# before
replicas:
  - type: oss
    region: cn-hangzhou
# after
replicas:
  - type: oss
    region: cn-hangzhou
    bucket: my-db-backups

Defensive patterns

Strategy: validation

Validate before calling

// Ensure the OSS bucket resolves to a non-empty value before starting
if cfg.Bucket == "" && !strings.HasPrefix(strings.TrimPrefix(cfg.URL, "oss://"), validBucketName) {
    return fmt.Errorf("oss replica bucket missing")
}

Try / catch

if err := runReplicate(); err != nil {
    if strings.Contains(err.Error(), "bucket required for oss") {
        // add bucket to config or URL
    }
}

Prevention

Set bucket explicitly in the replica block; avoid relying on env vars that may be unset.
Validate config with a dry run before deploying to production.

When it happens

Trigger: Configuring an OSS replica with only `region`/`endpoint`/credentials but no `bucket` and a URL without a bucket component.

Common situations: Writing `oss://` with no bucket; forgetting the bucket key entirely when first setting up OSS; env-based config where the bucket variable expands to empty.

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/93c66f5db0474965. Report an issue: GitHub.