{"record":{"id":"aa3e403a9ef69e6a","repo":"benbjohnson/litestream","slug":"multiple-replicas-on-a-single-database-are-no-long","errorCode":null,"errorMessage":"multiple replicas on a single database are no longer supported","messagePattern":"multiple replicas on a single database are no longer supported","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/main.go","lineNumber":795,"sourceCode":"\t\tdb.MinCheckpointPageN = *dbc.MinCheckpointPageN\n\t}\n\tif dbc.TruncatePageN != nil {\n\t\tdb.TruncatePageN = *dbc.TruncatePageN\n\t}\n\tif dbc.MaxSyncWALBytes != nil {\n\t\tdb.MaxSyncWALBytes = *dbc.MaxSyncWALBytes\n\t}\n\n\t// Instantiate and attach replica.\n\t// v0.3.x and before supported multiple replicas but that was dropped to\n\t// ensure there's a single remote data authority.\n\tswitch {\n\tcase dbc.Replica == nil && len(dbc.Replicas) == 0:\n\t\treturn nil, fmt.Errorf(\"must specify replica for database\")\n\tcase dbc.Replica != nil && len(dbc.Replicas) > 0:\n\t\treturn nil, fmt.Errorf(\"cannot specify 'replica' and 'replicas' on a database\")\n\tcase len(dbc.Replicas) > 1:\n\t\treturn nil, fmt.Errorf(\"multiple replicas on a single database are no longer supported\")\n\t}\n\n\tvar rc *ReplicaConfig\n\tif dbc.Replica != nil {\n\t\trc = dbc.Replica\n\t} else {\n\t\trc = dbc.Replicas[0]\n\t}\n\n\tr, err := NewReplicaFromConfig(rc, db)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tdb.Replica = r\n\n\treturn db, nil\n}\n","sourceCodeStart":777,"sourceCodeEnd":813,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/main.go#L777-L813","documentation":"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.","triggerScenarios":"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.","commonSituations":"Upgrading from Litestream v0.3.x or earlier where multiple replicas per database were allowed; archived configs reused with a modern binary.","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."],"exampleFix":"# before (v0.3.x style)\ndatabases:\n  - path: /var/db/app.db\n    replicas:\n      - url: s3://bucket-a/app\n      - url: s3://bucket-b/app\n# after\ndatabases:\n  - path: /var/db/app.db\n    replica:\n      url: s3://bucket-a/app","handlingStrategy":"validation","validationCode":"if len(dbc.Replicas) > 1 {\n    return fmt.Errorf(\"only one replica supported\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["config","replica","deprecated","migration","litestream"],"backgroundTag":"unsupported-config-value","analyzedSha":"4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3","analyzedAt":"2026-09-06T18:29:25.564Z","contentChangedAt":"2026-09-06T18:29:25.564Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}