benbjohnson/litestream · error

oss: invalid url scheme

Error message

oss: invalid url scheme

What it means

Validation guard in the OSS client's ParseURL: the URL must use the 'oss' scheme. Fires when a replica URL with another scheme (e.g. s3:// or https://) is passed to OSS URL parsing, typically from a misconfigured replica URL.

Source

Thrown at oss/replica_client.go:631

// Item returns the metadata for the current file.
func (itr *fileIterator) Item() *ltx.FileInfo {
	return itr.info
}

// Err returns any error that occurred during iteration.
func (itr *fileIterator) Err() error {
	return itr.err
}

// ParseURL parses an OSS URL into its host and path parts.
func ParseURL(s string) (bucket, region, key string, err error) {
	u, err := url.Parse(s)
	if err != nil {
		return "", "", "", err
	}

	if u.Scheme != "oss" {
		return "", "", "", fmt.Errorf("oss: invalid url scheme")
	}

	// Parse host to extract bucket and region
	bucket, region, _ = ParseHost(u.Host)
	if bucket == "" {
		bucket = u.Host
	}

	key = strings.TrimPrefix(u.Path, "/")
	return bucket, region, key, nil
}

// ParseHost parses the host/endpoint for an OSS storage system.
// Supports formats like:
//   - bucket.oss-cn-hangzhou.aliyuncs.com
//   - bucket.oss-cn-hangzhou-internal.aliyuncs.com
//   - bucket (just bucket name)
func ParseHost(host string) (bucket, region, endpoint string) {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Use the oss:// scheme: url: "oss://my-bucket.oss-cn-hangzhou.aliyuncs.com/path".
2. If the backend is actually S3 or another provider, use the matching replica type instead of the OSS client.
3. Fix typos in the scheme ('os', 'OSS:' variants are rejected; scheme comparison is exact).
4. Check that env expansion hasn't mangled the URL (e.g. unescaped $ in the config value).

Example fix

// before
url: "https://my-bucket.oss-cn-hangzhou.aliyuncs.com/db/ltx"
// after
url: "oss://my-bucket.oss-cn-hangzhou.aliyuncs.com/db/ltx"

u, _ := url.Parse(replicaURL)
if u.Scheme != "oss" {
    return fmt.Errorf("oss replica URL must use oss:// scheme, got %q", u.Scheme)
}

When it happens

Trigger: Configuring a replica with a URL whose scheme is not oss://, e.g. 's3://bucket/path', 'https://bucket.oss-cn-hangzhou.aliyuncs.com/path', or a typo like 'os://bucket/path' passed through NewReplicaClientFromURL / config parsing.

Common situations: Copy-pasting an S3 replica URL into an OSS replica entry; putting an https endpoint URL where the litestream URL is expected; case/scheme typos in litestream.yml.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• heartbeat URL must be a valid HTTP or HTTPS URL
• file replica path required
• bucket required for gs replica URL
• oss: bucket name is required
• replica url scheme required: %s

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