What causes "must specify replica for database" in benbjohnson/litestream?

Add a `replica:` section with a storage backend (e.g. `url: s3://bucket/db`) to the database entry.

must specify replica for database

Error message

must specify replica for database

What it means

NewDBFromConfig requires every database to have exactly one replication target. Since v0.3.x, multiple replicas were dropped to keep a single remote data authority; a DBConfig with Replica == nil and empty Replicas yields this error because there is nothing to replicate to.

Source

Thrown at cmd/litestream/main.go:791

	if dbc.BusyTimeout != nil {
		db.BusyTimeout = *dbc.BusyTimeout
	}
	if dbc.MinCheckpointPageN != nil {
		db.MinCheckpointPageN = *dbc.MinCheckpointPageN
	}
	if dbc.TruncatePageN != nil {
		db.TruncatePageN = *dbc.TruncatePageN
	}
	if dbc.MaxSyncWALBytes != nil {
		db.MaxSyncWALBytes = *dbc.MaxSyncWALBytes
	}

	// Instantiate and attach replica.
	// v0.3.x and before supported multiple replicas but that was dropped to
	// ensure there's a single remote data authority.
	switch {
	case dbc.Replica == nil && len(dbc.Replicas) == 0:
		return nil, fmt.Errorf("must specify replica for database")
	case dbc.Replica != nil && len(dbc.Replicas) > 0:
		return nil, fmt.Errorf("cannot specify 'replica' and 'replicas' on a database")
	case len(dbc.Replicas) > 1:
		return nil, fmt.Errorf("multiple replicas on a single database are no longer supported")
	}

	var rc *ReplicaConfig
	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

View on GitHub (pinned to 4ed7a308f6)

Solutions

Add a `replica:` section with a storage backend (e.g. `url: s3://bucket/db`) to the database entry.
If using directory replication, set the replica URL at the directory-config level as documented.
Verify the YAML indentation so the replica key is nested under the correct databases entry.

Example fix

# before
databases:
  - path: /var/db/app.db
# after
databases:
  - path: /var/db/app.db
    replica:
      url: s3://mybucket/litestream/app

Defensive patterns

Strategy: validation

Validate before calling

if dbc.Replica == nil && len(dbc.Replicas) == 0 {
    return fmt.Errorf("db #%d needs a replica", i+1)
}

Prevention

Always include a replica block per database entry
Start from the official config template
Validate the full config before deploying

When it happens

Trigger: A databases[] entry defines a path (or dir) but no `replica:` section and no (deprecated) `replicas:` list; NewDBFromConfig is called from Run, newDBFromDirectoryEntry, or loadFromConfig.

Common situations: New config written with only the database path, forgetting the replica block; comment/template stripped the replica section; migration from an older config omitted replicas.

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