What causes "failed to create DB for %s: %w" in benbjohnson/litestream?

Look at the wrapped inner error and the %s path in the message to find the specific failing database.

failed to create DB for %s: %w

Error message

failed to create DB for %s: %w

What it means

For each discovered database, newDBFromDirectoryEntry builds a per-DB litestream.DB. If constructing any individual DB fails (bad path, invalid replica config, etc.), the error is wrapped with the offending database path so the misconfigured entry is identifiable.

Source

Thrown at cmd/litestream/main.go:849

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

	// Create DB instances for each found database
	var dbs []*litestream.DB
	metaPaths := make(map[string]string)

	for _, dbPath := range dbPaths {
		db, err := newDBFromDirectoryEntry(dbc, dirPath, dbPath)
		if err != nil {
			return nil, fmt.Errorf("failed to create DB for %s: %w", dbPath, err)
		}

		// Validate unique meta-path to prevent replication state corruption
		if mp := db.MetaPath(); mp != "" {
			if existingDB, exists := metaPaths[mp]; exists {
				return nil, fmt.Errorf("meta-path collision: databases %s and %s would share meta-path %s, causing replication state corruption", existingDB, dbPath, mp)
			}
			metaPaths[mp] = dbPath
		}

		dbs = append(dbs, db)
	}

	return dbs, nil
}

// newDBFromDirectoryEntry creates a DB instance for a database discovered via directory replication.
func newDBFromDirectoryEntry(dbc *DBConfig, dirPath, dbPath string) (*litestream.DB, error) {

View on GitHub (pinned to 4ed7a308f6)

Solutions

Look at the wrapped inner error and the %s path in the message to find the specific failing database.
Fix the underlying issue for that file (rename it, fix its derived meta path, correct the replica config).
Narrow the pattern to exclude files that should not be treated as databases.
Test the same config against a single-DB stanza for that path to isolate the failure.

Example fix

# before
pattern: "**/*"  # matches logs, temp files, everything

# after
pattern: "**/*.db"  # only real database files

Defensive patterns

Strategy: try-catch

Try / catch

dbs, err := NewDBsFromDirectoryConfig(dbc)
if err != nil {
    var e *fmt.WrapError // inspect message for "failed to create DB for <path>"
    log.Fatalf("directory replication setup failed: %v", err)
}

Prevention

Keep database filenames simple (ASCII, no spaces) for directory replication.
Narrow the pattern so only real SQLite files match.
Validate the replica config independently before enabling directory mode.

When it happens

Trigger: newDBFromDirectoryEntry(dbc, dirPath, dbPath) returns an error for a specific dbPath — including any of errors 106/107/108/109 or failures inside litestream.NewDB (e.g. unwritable meta path).

Common situations: One database file in the scanned directory has a pathological name (unusual characters breaking path/URL derivation); replica URL invalid; meta directory not creatable for one entry; a file matches the glob but is not a real SQLite database.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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