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

Add a `pattern` to the database config, e.g. `pattern: "*.db"` or `pattern: "**/*.sqlite*"`.

pattern is required for directory replication

Error message

pattern is required for directory replication

What it means

Directory replication in Litestream watches a directory of SQLite databases matched by a glob pattern. When a DB config sets 'dir' (directory replication) but the 'pattern' field is empty, NewDBsFromDirectoryConfig cannot know which files are databases and returns this error instead of starting replication.

Source

Thrown at cmd/litestream/main.go:821

	}

	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)
	}

	if len(dbPaths) == 0 && !dbc.Watch {
		return nil, fmt.Errorf("no SQLite databases found in directory %s with pattern %s", dirPath, dbc.Pattern)

View on GitHub (pinned to 4ed7a308f6)

Solutions

Add a `pattern` to the database config, e.g. `pattern: "*.db"` or `pattern: "**/*.sqlite*"`.
If you meant to replicate a single database, remove `dir` and set `path:` to the database file instead.
Verify the YAML key is spelled `pattern` and is nested under the correct db entry.

Example fix

# before
dbs:
  - dir: /var/lib/myapp
    replicas:
      - url: s3://bucket/db

# after
dbs:
  - dir: /var/lib/myapp
    pattern: "*.db"
    replicas:
      - url: s3://bucket/db

Defensive patterns

Strategy: validation

Validate before calling

if dbc.Dir != "" && dbc.Pattern == "" {
    return fmt.Errorf("directory replication requires `pattern` (e.g. \"*.db\")")
}

Prevention

Always pair `dir:` with `pattern:` in litestream configs.
Use a config linter or JSON/YAML schema to require pattern when dir is present.
Prefer `path:` for single databases so directory validation never applies.

When it happens

Trigger: Calling NewDBsFromDirectoryConfig (directly or via Run/startDirectoryMonitor) with a DBConfig whose Dir is non-empty but Pattern is "".

Common situations: User writes a config with `dir: /var/lib/db` but forgets the `pattern:` key; a config-generation tool omits pattern; a YAML typo like `patten:` silently leaves Pattern 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/5a5ff055350caec4. Report an issue: GitHub.