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

Set an absolute directory path in the file replica URL, e.g. file:///var/lib/litestream/db.

file replica path required

Error message

file replica path required

What it means

The file replica client factory requires a path component in a file:// replica URL because for file URLs the path is where replica data is stored. NewReplicaClientFromURL returns this error when a file-scheme URL has an empty path, e.g. file:// with no target directory.

Source

Thrown at file/replica_client.go:57

// NewReplicaClient returns a new instance of ReplicaClient.
func NewReplicaClient(path string) *ReplicaClient {
	return &ReplicaClient{
		logger: slog.Default().WithGroup(ReplicaClientType),
		path:   path,
	}
}

func (c *ReplicaClient) SetLogger(logger *slog.Logger) {
	c.logger = logger.WithGroup(ReplicaClientType)
}

// NewReplicaClientFromURL creates a new ReplicaClient from URL components.
// This is used by the replica client factory registration.
func NewReplicaClientFromURL(scheme, host, urlPath string, query url.Values, userinfo *url.Userinfo) (litestream.ReplicaClient, error) {
	// For file URLs, the path is the full path
	if urlPath == "" {
		return nil, fmt.Errorf("file replica path required")
	}
	return NewReplicaClient(urlPath), nil
}

// db returns the database, if available.
func (c *ReplicaClient) db() *litestream.DB {
	if c.Replica == nil {
		return nil
	}
	return c.Replica.DB()
}

// Type returns "file" as the client type.
func (c *ReplicaClient) Type() string {
	return ReplicaClientType
}

// Init is a no-op for file replica client as no initialization is required.

View on GitHub (pinned to 4ed7a308f6)

Solutions

Set an absolute directory path in the file replica URL, e.g. file:///var/lib/litestream/db.
Check config expansion ($ENV_VAR, $PID) didn't produce an empty path segment.
Validate the URL before creating the replica: require a non-empty Path for the file scheme.
When building URLs programmatically, set url.Path to the intended directory.

Example fix

// before (litestream.yml)
replicas:
  - url: file://
// after
replicas:
  - url: file:///var/backups/litestream/mydb

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(replicaURL)
if err != nil || u.Scheme != "file" { return fmt.Errorf("not a file replica URL") }
if u.Path == "" { return fmt.Errorf("file replica path required") }

Type guard

func validFileReplicaURL(u *url.URL) bool { return u != nil && u.Scheme == "file" && u.Path != "" }

Try / catch

if _, err := NewReplicaClientFromURL("file", u.Host, u.Path, u.Query(), u.User); err != nil {
    return fmt.Errorf("invalid file replica URL %q: %w", replicaURL, err)
}

Prevention

Always use absolute paths in file:// replica URLs.
Check env-var expansion didn't blank the path at config load.
Validate all replica URLs at startup before registering replicas.

When it happens

Trigger: Configuring a file replica with URL like file:// (no path), or programmatically registering a replica whose URL path is empty, then instantiating the client via the URL factory.

Common situations: YAML config with `url: file://` missing the directory; templated config where a path variable expanded to empty; hand-built url.URL with only the scheme set.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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