benbjohnson/litestream · error

cannot specify 'replica' and 'replicas' on a database

Error message

cannot specify 'replica' and 'replicas' on a database

What it means

NewDBFromConfig enforces a single replication target: a DBConfig may set the current `replica` field or the deprecated `replicas` list, never both. Specifying both is ambiguous about the authoritative replica, so DB creation fails with this error.

Source

Thrown at cmd/litestream/main.go:793

	}
	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

	return db, nil

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Delete the deprecated `replicas:` list and keep only the single `replica:` entry.
2. Migrate old multi-replica configs: v0.3.x replicas can be restored via the v0.3.x restore path, but new replication must target one replica.
3. Re-run `litestream` after cleanup to confirm the config validates.

Example fix

# before
databases:
  - path: /var/db/app.db
    replica:
      url: s3://bucket/app
    replicas:
      - url: s3://bucket2/app
# after
databases:
  - path: /var/db/app.db
    replica:
      url: s3://bucket/app

if dbc.Replica != nil && len(dbc.Replicas) > 0 {
    return fmt.Errorf("use only 'replica', not both")
}

When it happens

Trigger: A databases[] entry contains a top-level `replica:` key while also having a non-empty `replicas:` list (the v0.3.x-era plural form); caught when Run/loadFromConfig calls NewDBFromConfig.

Common situations: Merging an old v0.3.x config (replicas list) with a new config (single replica) into the same entry; copy-paste from docs of two eras.

Related errors

• multiple replicas on a single database are no longer support
• must specify replica for database
• failed to configure replica for %s: %w
• failed to configure replica %d for %s: %w
• age encryption is not currently supported, if you need encry

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