What causes "parse replica url: %w" in benbjohnson/litestream?

Fix the replica `url` value so it is a valid URL (check percent-escapes and brackets)

parse replica url: %w

Error message

parse replica url: %w

What it means

Raised when the `url` field of a replica config in the deprecated replicas array cannot be parsed by Go's net/url.Parse while rewriting it with the database's relative path. The parse error is chained, and the surrounding database fails to load.

Source

Thrown at cmd/litestream/main.go:946

// cloneReplicaConfigWithRelativePath returns a copy of the replica configuration with the
// database-relative path appended to either the replica path or URL, depending on how the
// replica was configured.
func cloneReplicaConfigWithRelativePath(base *ReplicaConfig, relPath string) (*ReplicaConfig, error) {
	if base == nil {
		return nil, nil
	}

	replicaCopy := *base
	relPath = filepath.ToSlash(relPath)
	if relPath == "" || relPath == "." {
		return &replicaCopy, nil
	}

	if replicaCopy.URL != "" {
		u, err := url.Parse(replicaCopy.URL)
		if err != nil {
			return nil, fmt.Errorf("parse replica url: %w", err)
		}
		appendRelativePathToURL(u, relPath)
		replicaCopy.URL = u.String()
		return &replicaCopy, nil
	}

	switch base.ReplicaType() {
	case "file":
		relOSPath := filepath.FromSlash(relPath)
		if replicaCopy.Path != "" {
			replicaCopy.Path = filepath.Join(replicaCopy.Path, relOSPath)
		} else {
			replicaCopy.Path = relOSPath
		}
	default:
		// Normalize to forward slashes for cloud/object storage backends.
		basePath := filepath.ToSlash(replicaCopy.Path)
		if basePath != "" {

View on GitHub (pinned to 4ed7a308f6)

Solutions

Fix the replica `url` value so it is a valid URL (check percent-escapes and brackets)
Check the wrapped %w error for the exact parse failure position
Validate the URL with a quick `python3 -c`/curl test or Go snippet before deploying the config

Example fix

# before
replicas:
  - url: s3://%ZZ@bucket/db
# after
replicas:
  - url: s3://bucket/db

Defensive patterns

Strategy: validation

Validate before calling

if _, err := url.Parse(replica.URL); err != nil {
    return fmt.Errorf("replica url %q invalid: %w", replica.URL, err)
}

Prevention

Validate replica URLs with net/url.Parse before writing configs
Avoid raw env interpolation into URLs; quote and escape values
Keep URLs ASCII without stray percent signs

When it happens

Trigger: A replica entry whose `url` string is malformed for Go's url.Parse (e.g. invalid percent-encoding like `%zz`, control characters) encountered during config-directory loading.

Common situations: Hand-edited YAML with a broken URL (missing scheme is usually fine for url.Parse, but `http://[bad-ipv6` or stray `%` sequences are not); shell-interpolated env vars producing garbage in the URL.

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

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