What causes "host required for sftp replica" in benbjohnson/litestream?

Add 'host: ' to the sftp replica config

host required for sftp replica

Error message

host required for sftp replica

What it means

After applying URL-derived values, newSFTPReplicaClientFromConfig requires a non-empty host. The SFTP replica client cannot connect without an SSH host, so if neither 'host' nor the host component of 'url' was provided, this error is returned at startup.

Source

Thrown at cmd/litestream/main.go:1836

		// Only apply URL parts to field that have not been overridden.
		if host == "" {
			host = u.Host
		}
		if user == "" && u.User != nil {
			user = u.User.Username()
		}
		if password == "" && u.User != nil {
			password, _ = u.User.Password()
		}
		if path == "" {
			path = u.Path
		}
	}

	// Ensure required settings are set.
	if host == "" {
		return nil, fmt.Errorf("host required for sftp replica")
	} else if user == "" {
		return nil, fmt.Errorf("user required for sftp replica")
	}

	// Build replica.
	client := sftp.NewReplicaClient()
	client.Host = host
	client.User = user
	client.Password = password
	client.Path = path
	client.KeyPath = c.KeyPath
	client.HostKey = c.HostKey

	// Set concurrent writes if specified, otherwise use default (true)
	if c.ConcurrentWrites != nil {
		client.ConcurrentWrites = *c.ConcurrentWrites
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

Add 'host: <sftp-server>' to the sftp replica config
Or set a full URL including host: 'url: sftp://user@hostname/path'
Check that any env var used to build the config is actually set at process start

Example fix

# before
- type: sftp
  user: backup
  path: /srv/backup
# after
- type: sftp
  host: backup.example.com
  user: backup
  path: /srv/backup

Defensive patterns

Strategy: validation

Validate before calling

if rep.Type == "sftp" {
    host := rep.Host
    if host == "" && rep.URL != "" {
        if u, err := url.Parse(rep.URL); err == nil { host = u.Host }
    }
    if host == "" { return fmt.Errorf("sftp replica %s: missing host", rep.Name) }
}

Prevention

Always set host explicitly for sftp replicas
Use full URLs (scheme://user@host/path) to avoid empty-host parses
Check env-var expansion at deploy time so hosts aren't blank

When it happens

Trigger: An sftp replica with no 'host' field and a 'url' whose host part is empty (e.g. url: 'sftp:///backup' or a bare path), or no url at all.

Common situations: Config with only user/path/key-path fields assuming host comes from an environment variable that was unset; malformed url like 'sftp:/backup' (single slash) that parses with an empty host.

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