benbjohnson/litestream · error

cannot specify url & path for file replica

Error message

cannot specify url & path for file replica

What it means

A file replica may be described either by a `url` (file://...) or a `path`, but newFileReplicaClientFromConfig forbids specifying both, since the source of the destination directory would be ambiguous.

Source

Thrown at cmd/litestream/main.go:1424

		}
	case "oss":
		if r.Client, err = newOSSReplicaClientFromConfig(c, r); err != nil {
			return nil, err
		}
	default:
		return nil, fmt.Errorf("unknown replica type in config: %q", c.ReplicaType())
	}

	r.Client.SetLogger(r.Logger())

	return r, nil
}

// 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

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Delete the `path` field and keep only `url`
2. Or delete `url` and keep only `path`
3. Keep exactly one of the two fields per file replica entry

Example fix

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

if r.URL != "" && r.Path != "" {
    return errors.New("file replica: set either url or path, not both")
}

When it happens

Trigger: Replica config has both a non-empty `url` (e.g. `file:///backups/db`) and a non-empty `path` (e.g. `path: /backups/db`) for a file-type replica.

Common situations: Merging an old path-based config with a new url-based one; template-generated config where defaults set `path` and users also set `url`.

Related errors

• file replica path required
• config file not found
• %w: %s
• must specify replica for database
• cannot specify 'replica' and 'replicas' on a database

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