What causes "directory path is required for directory replication" in benbjohnson/litestream?

Add `dir: /path/to/directory` to the databases entry.

directory path is required for directory replication

Error message

directory path is required for directory replication

What it means

NewDBsFromDirectoryConfig scans a directory and creates DB instances for all SQLite databases found; it first verifies that dbc.Dir is non-empty. An empty dir means there is nothing to scan, so directory replication cannot proceed and this error is returned before the pattern check.

Source

Thrown at cmd/litestream/main.go:817

	if dbc.Replica != nil {
		rc = dbc.Replica
	} else {
		rc = dbc.Replicas[0]
	}

	r, err := NewReplicaFromConfig(rc, db)
	if err != nil {
		return nil, err
	}
	db.Replica = r

	return db, nil
}

// NewDBsFromDirectoryConfig scans a directory and creates DB instances for all SQLite databases found.
func NewDBsFromDirectoryConfig(dbc *DBConfig) ([]*litestream.DB, error) {
	if dbc.Dir == "" {
		return nil, fmt.Errorf("directory path is required for directory replication")
	}

	if dbc.Pattern == "" {
		return nil, fmt.Errorf("pattern is required for directory replication")
	}
	if dbc.MetaPath != nil && dbc.MetaDir != nil {
		return nil, fmt.Errorf("cannot specify both 'meta-path' and 'meta-dir'")
	}

	dirPath, err := expand(dbc.Dir)
	if err != nil {
		return nil, err
	}

	// Find all SQLite databases in the directory
	dbPaths, err := FindSQLiteDatabases(dirPath, dbc.Pattern, dbc.Recursive)
	if err != nil {
		return nil, fmt.Errorf("failed to scan directory %s: %w", dirPath, err)

View on GitHub (pinned to 4ed7a308f6)

Solutions

Add `dir: /path/to/directory` to the databases entry.
Check for misspelled keys (`directory` vs `dir`) and verify env variables used in the dir value are non-empty.
If you meant a single database, use `path:` instead of directory options.

Example fix

# before
databases:
  - pattern: "*.db"
# after
databases:
  - dir: /var/db
    pattern: "*.db"

Defensive patterns

Strategy: validation

Validate before calling

if dbc.Dir == "" {
    return fmt.Errorf("directory replication requires 'dir'")
}

Prevention

Set dir (exact key name) on directory-replication entries
Verify env-expanded dir values are non-empty
Validate configs before start

When it happens

Trigger: Calling NewDBsFromDirectoryConfig (from startDirectoryMonitor or Run) with a DBConfig whose Dir field is "" — e.g. a databases[] entry intended for directory replication that only sets `pattern:` or neither `path:` nor `dir:`.

Common situations: YAML entry with `watch: true`/`pattern:` but the `dir:` key missing or misspelled (`directory:`); env-expansion of dir resolved to empty string.

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