What causes "file replica path required" in benbjohnson/litestream?

Set `path: /absolute/or/~/relative/dir` on the file replica

file replica path required

Error message

file replica path required

What it means

newFileReplicaClientFromConfig found neither url nor path set on the file replica config, so there is no directory to replicate into. It is the guard after the both-set check: the replica destination is simply missing.

Source

Thrown at cmd/litestream/main.go:1437

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

	// Parse configPath from URL, if specified.
	configPath := c.Path
	if c.URL != "" {
		if _, _, configPath, err = litestream.ParseReplicaURL(c.URL); err != nil {
			return nil, err
		}
	}

	// Ensure path is set explicitly or derived from URL field.
	if configPath == "" {
		return nil, fmt.Errorf("file replica path required")
	}

	// Expand home prefix and return absolute path.
	if configPath, err = expand(configPath); err != nil {
		return nil, err
	}

	// Instantiate replica and apply time fields, if set.
	client := file.NewReplicaClient(configPath)
	client.Replica = r
	return client, nil
}

// NewS3ReplicaClientFromConfig returns a new instance of s3.ReplicaClient built from config.
// Exported for testing.
func NewS3ReplicaClientFromConfig(c *ReplicaConfig, _ *litestream.Replica) (_ *s3.ReplicaClient, err error) {
	// Ensure URL & constituent parts are not both specified.
	if c.URL != "" && c.Path != "" {

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set `path: /absolute/or/~/relative/dir` on the file replica
Or set a full `url: file:///backups/db` including the path part
Check that any env var used in the path is set at launch

Example fix

# before
replicas:
  - url: file://
# after
replicas:
  - url: file:///var/backups/db

Defensive patterns

Strategy: validation

Validate before calling

u, _ := url.Parse(r.URL)
if r.Path == "" && (u == nil || u.Path == "" || u.Path == "/") {
    return errors.New("file replica requires path or url with a path component")
}

Prevention

Always give file replicas an explicit absolute path
Avoid bare `file://` URLs without a path
Check env-expanded path values are non-empty before launch

When it happens

Trigger: A file replica with neither `path` nor a `url` containing a path component (e.g. `url: file://` or `url: file://host` with empty path), so configPath stays "".

Common situations: Config entry `- url: file://` with trailing slashes stripped by an editor; a replica block that only sets `type: file` with no destination; env-var expansion in the path resolving to empty.

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