{"record":{"id":"e2f80e85cd396cd3","repo":"benbjohnson/litestream","slug":"cannot-specify-a-replica-url-and-the-config-flag","errorCode":null,"errorMessage":"cannot specify a replica URL and the -config flag","messagePattern":"cannot specify a replica URL and the -config flag","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/litestream/replicate.go","lineNumber":109,"sourceCode":"\t\tif *logLevelFlag != \"\" {\n\t\t\tc.Config.Logging.Level = *logLevelFlag\n\t\t\t// Set env var so initLog sees CLI flag as highest priority\n\t\t\tos.Setenv(\"LOG_LEVEL\", *logLevelFlag)\n\t\t\tlogOutput := os.Stdout\n\t\t\tif c.Config.Logging.Stderr {\n\t\t\t\tlogOutput = os.Stderr\n\t\t\t}\n\t\t\tinternal.InitLog(logOutput, c.Config.Logging.Level, c.Config.Logging.Type, c.Config.Logging.Source)\n\t\t}\n\n\tcase 1:\n\t\t// Only database path provided, missing replica URL\n\t\treturn fmt.Errorf(\"must specify at least one replica URL for %s\", fs.Arg(0))\n\n\tdefault:\n\t\t// Database path and replica URLs provided via CLI\n\t\tif *configPath != \"\" {\n\t\t\treturn fmt.Errorf(\"cannot specify a replica URL and the -config flag\")\n\t\t}\n\n\t\t// Initialize config with defaults when using command-line arguments\n\t\tc.Config = DefaultConfig()\n\t\tlogLevel := \"INFO\"\n\t\tif *logLevelFlag != \"\" {\n\t\t\tlogLevel = *logLevelFlag\n\t\t\t// Set env var so initLog sees CLI flag as highest priority\n\t\t\tos.Setenv(\"LOG_LEVEL\", *logLevelFlag)\n\t\t}\n\t\tc.Config.Logging.Level = logLevel\n\t\tinternal.InitLog(os.Stdout, logLevel, \"text\", false)\n\n\t\tdbConfig := &DBConfig{\n\t\t\tPath:                 fs.Arg(0),\n\t\t\tRestoreIfDBNotExists: *restoreIfDBNotExists,\n\t\t}\n\t\tfor _, u := range fs.Args()[1:] {","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/benbjohnson/litestream/blob/4ed7a308f6271ebfd2b0a6e4b70b03011a37e4a3/cmd/litestream/replicate.go#L91-L127","documentation":"replicate's flags and replica URLs are mutually exclusive: when replica URLs are supplied as positional args, no -config flag may be given, since the config would define its own DB/replica set and the CLI args would conflict. ParseFlags enforces this in the default (≥2 args) branch.","triggerScenarios":"Running `litestream replicate -config /etc/litestream.yml /path/to/db s3://bucket/prefix`; wrapping scripts that always append -config while also passing explicit DB+replica args.","commonSituations":"Users combining an existing config file with ad-hoc replicas; migration scripts templated with both styles of invocation; misunderstanding that -config only supplies defaults.","solutions":["Choose one mode: either drop the positional args and rely solely on -config, or drop -config and pass DB path + replica URL(s) on the command line","If you need config defaults plus one override, edit the config file to include that replica instead","In scripts, branch: use -config when CONFIG is set, otherwise build the positional args"],"exampleFix":"// before\nlitestream replicate -config /etc/litestream.yml /db.sqlite s3://bucket/prefix\n// after (option A)\nlitestream replicate -config /etc/litestream.yml\n// after (option B)\nlitestream replicate /db.sqlite s3://bucket/prefix","handlingStrategy":"validation","validationCode":"if [ -n \"$CONFIG\" ] && [ -n \"$REPLICA_URL\" ]; then echo \"cannot combine -config with positional replica URLs\"; exit 1; fi","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pick one invocation mode per command: config file OR positional args","In scripts, branch explicitly on whether CONFIG is set","Remember -config cannot be used to 'override' CLI-supplied replicas"],"tags":["cli","flags","configuration"],"backgroundTag":"mutually-exclusive-flags","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"}