{"record":{"id":"dea32d485be5a719","repo":"benbjohnson/litestream","slug":"cannot-specify-replica-and-replicas-on-a-datab","errorCode":null,"errorMessage":"cannot specify 'replica' and 'replicas' on a database","messagePattern":"cannot specify 'replica' and 'replicas' on a database","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/main.go","lineNumber":793,"sourceCode":"\t}\n\tif dbc.MinCheckpointPageN != nil {\n\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","sourceCodeStart":775,"sourceCodeEnd":811,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/main.go#L775-L811","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Delete the deprecated `replicas:` list and keep only the single `replica:` entry.","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.","Re-run `litestream` after cleanup to confirm the config validates."],"exampleFix":"# before\ndatabases:\n  - path: /var/db/app.db\n    replica:\n      url: s3://bucket/app\n    replicas:\n      - url: s3://bucket2/app\n# after\ndatabases:\n  - path: /var/db/app.db\n    replica:\n      url: s3://bucket/app","handlingStrategy":"validation","validationCode":"if dbc.Replica != nil && len(dbc.Replicas) > 0 {\n    return fmt.Errorf(\"use only 'replica', not both\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Migrate v0.3.x configs: drop replicas list, keep single replica","Grep configs for 'replicas:' before upgrading","Keep one replica per database by design"],"tags":["config","replica","deprecated","litestream"],"backgroundTag":"mutually-exclusive-options","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"}