multiple replicas on a single database are no longer support

Error message

multiple replicas on a single database are no longer supported

What it means

NewDBFromConfig rejects DBConfigs with more than one entry in the deprecated Replicas list. Litestream dropped multi-replica support to ensure a single remote data authority, so a replicas list longer than one element is no longer supported.

Source

Thrown at cmd/litestream/main.go:795

		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

Keep a single replica: pick the primary target and configure it as `replica:`.
Replicate to additional destinations by running separate Litestream processes/configs (one destination each), since one destination per DB is the model.
Use `litestream restore`/v0.3.x-compatible restore (ReplicaClientV3) to recover data from the old secondary replicas before removing them from config.

Example fix

# before (v0.3.x style)
databases:
  - path: /var/db/app.db
    replicas:
      - url: s3://bucket-a/app
      - url: s3://bucket-b/app
# after
databases:
  - path: /var/db/app.db
    replica:
      url: s3://bucket-a/app

Defensive patterns

Strategy: validation

Validate before calling

if len(dbc.Replicas) > 1 {
    return fmt.Errorf("only one replica supported")
}

Prevention

Archive old multi-replica configs separately from new ones
Run separate Litestream instances for extra destinations
Read the migration guide when moving from v0.3.x

When it happens

Trigger: A databases[] entry from a pre-v0.3.x-style config lists two or more `replicas:`; NewDBFromConfig hits the `len(dbc.Replicas) > 1` case via Run/newDBFromDirectoryEntry/loadFromConfig.

Common situations: Upgrading from Litestream v0.3.x or earlier where multiple replicas per database were allowed; archived configs reused with a modern binary.

Related errors

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