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

Add 'user: ' to the sftp replica config

user required for sftp replica

Error message

user required for sftp replica

What it means

newSFTPReplicaClientFromConfig requires a username: after merging 'url' userinfo with the 'user' field, the user must be non-empty because the SFTP client needs a login account. This error is returned when both sources are empty.

Source

Thrown at cmd/litestream/main.go:1838

		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
	}

	return client, nil
}

View on GitHub (pinned to 4ed7a308f6)

Solutions

Add 'user: <username>' to the sftp replica config
Or include the user in the URL: 'url: sftp://myuser@host/path'
Confirm the auth approach: litestream needs an explicit user even when key-path auth is used

Example fix

# before
- type: sftp
  host: backup.example.com
  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" {
    user := rep.User
    if user == "" && rep.URL != "" {
        if u, err := url.Parse(rep.URL); err == nil && u.User != nil { user = u.User.Username() }
    }
    if user == "" { return fmt.Errorf("sftp replica %s: missing user", rep.Name) }
}

Prevention

Always specify 'user:' for sftp replicas, even with key auth
Include user@ in the URL when using URL-style config
Never assume SSH defaults apply; litestream requires explicit user

When it happens

Trigger: An sftp replica with no 'user' field and a 'url' lacking userinfo (e.g. 'sftp://host/backup'), so user remains empty after URL application.

Common situations: Relying on SSH default user or ssh-agent identity without specifying it (litestream requires an explicit user); a URL like 'sftp://host/db' without user@.

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