benbjohnson/litestream · error

cannot specify a replica URL and the -config flag

Error message

cannot specify a replica URL and the -config flag

What it means

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.

Source

Thrown at cmd/litestream/replicate.go:109

		if *logLevelFlag != "" {
			c.Config.Logging.Level = *logLevelFlag
			// Set env var so initLog sees CLI flag as highest priority
			os.Setenv("LOG_LEVEL", *logLevelFlag)
			logOutput := os.Stdout
			if c.Config.Logging.Stderr {
				logOutput = os.Stderr
			}
			internal.InitLog(logOutput, c.Config.Logging.Level, c.Config.Logging.Type, c.Config.Logging.Source)
		}

	case 1:
		// Only database path provided, missing replica URL
		return fmt.Errorf("must specify at least one replica URL for %s", fs.Arg(0))

	default:
		// Database path and replica URLs provided via CLI
		if *configPath != "" {
			return fmt.Errorf("cannot specify a replica URL and the -config flag")
		}

		// Initialize config with defaults when using command-line arguments
		c.Config = DefaultConfig()
		logLevel := "INFO"
		if *logLevelFlag != "" {
			logLevel = *logLevelFlag
			// Set env var so initLog sees CLI flag as highest priority
			os.Setenv("LOG_LEVEL", *logLevelFlag)
		}
		c.Config.Logging.Level = logLevel
		internal.InitLog(os.Stdout, logLevel, "text", false)

		dbConfig := &DBConfig{
			Path:                 fs.Arg(0),
			RestoreIfDBNotExists: *restoreIfDBNotExists,
		}
		for _, u := range fs.Args()[1:] {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. 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
2. If you need config defaults plus one override, edit the config file to include that replica instead
3. In scripts, branch: use -config when CONFIG is set, otherwise build the positional args

Example fix

// before
litestream replicate -config /etc/litestream.yml /db.sqlite s3://bucket/prefix
// after (option A)
litestream replicate -config /etc/litestream.yml
// after (option B)
litestream replicate /db.sqlite s3://bucket/prefix

if [ -n "$CONFIG" ] && [ -n "$REPLICA_URL" ]; then echo "cannot combine -config with positional replica URLs"; exit 1; fi

When it happens

Trigger: 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.

Common situations: Users combining an existing config file with ad-hoc replicas; migration scripts templated with both styles of invocation; misunderstanding that -config only supplies defaults.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

• cannot specify -once flag with -exec
• cannot specify -force-snapshot flag without -once
• cannot specify -enforce-retention flag without -once
• invalid -integrity-check value: %s
• cannot specify a replica URL and the -config flag

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