What causes "cannot specify url & path for sftp replica" in benbjohnson/litestream?

Remove the 'path' field from the sftp replica config and keep only 'url'

cannot specify url & path for sftp replica

Error message

cannot specify url & path for sftp replica

What it means

newSFTPReplicaClientFromConfig rejects replica configs that supply both the combined 'url' field and the individual 'path' field. The URL is meant to fully describe connection details; mixing it with separate constituent fields is ambiguous, so startup fails with this validation error.

Source

Thrown at cmd/litestream/main.go:1805

		}
		if client.Path == "" {
			client.Path = strings.TrimPrefix(path.Clean(u.Path), "/")
		}
	}

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

	return client, nil
}

// newSFTPReplicaClientFromConfig returns a new instance of sftp.ReplicaClient built from config.
func newSFTPReplicaClientFromConfig(c *ReplicaConfig, _ *litestream.Replica) (_ *sftp.ReplicaClient, err error) {
	// Ensure URL & constituent parts are not both specified.
	if c.URL != "" && c.Path != "" {
		return nil, fmt.Errorf("cannot specify url & path for sftp replica")
	} else if c.URL != "" && c.Host != "" {
		return nil, fmt.Errorf("cannot specify url & host for sftp replica")
	}

	host, user, password, path := c.Host, c.User, c.Password, c.Path

	// Apply settings from URL, if specified.
	if c.URL != "" {
		u, err := url.Parse(c.URL)
		if err != nil {
			return nil, err
		}

		// Only apply URL parts to field that have not been overridden.
		if host == "" {
			host = u.Host
		}
		if user == "" && u.User != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

Remove the 'path' field from the sftp replica config and keep only 'url'
Or remove 'url' and specify host/user/path fields individually
Encode the desired path inside the URL (sftp://user@host/<path>) instead of a separate key

Example fix

# before
- type: sftp
  url: sftp://user@host/backup
  path: /backup
# after
- type: sftp
  url: sftp://user@host/backup

Defensive patterns

Strategy: validation

Validate before calling

if rep.Type == "sftp" && rep.URL != "" && rep.Path != "" {
    return fmt.Errorf("sftp replica %s: url and path are mutually exclusive", rep.Name)
}

Try / catch

if err := litestream.NewReplicaClientFromConfig(cfg, rep); err != nil {
    if strings.Contains(err.Error(), "cannot specify url & path for sftp") {
        // sanitize config: drop path when url is set
    }
}

Prevention

Choose one config style per replica: url OR discrete fields
Lint configs to reject url+path combos for sftp/webdav/abs
Keep documentation examples single-style

When it happens

Trigger: An sftp replica config sets c.URL (e.g. 'sftp://user@host/backup') and also sets c.Path (e.g. path: /backup) at the same time.

Common situations: Merging an existing per-field sftp config with a new URL-based example copied from docs; a templated config that always emits 'path:' even when url is provided.

Related errors

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