benbjohnson/litestream · error

must specify at least one replica URL for %s

Error message

must specify at least one replica URL for %s

What it means

`litestream replicate` accepts a config file OR explicit CLI arguments, not a bare database path alone. If exactly one positional argument is given (a DB path with no replica URL), ParseFlags rejects it because replication needs at least one replica destination.

Source

Thrown at cmd/litestream/replicate.go:104

		}
		if c.Config, err = ReadConfigFile(*configPath, !*noExpandEnv); err != nil {
			return err
		}
		// Override log level if CLI flag provided (takes precedence over env var)
		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)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Add the replica URL: `litestream replicate /path/to/db s3://bucket/prefix`
2. Or point to a config: `litestream replicate -config /etc/litestream.yml`
3. Echo the command in your script to verify the replica argument isn't empty or lost to quoting

Example fix

// before
litestream replicate /var/lib/app/db.sqlite
// after
litestream replicate /var/lib/app/db.sqlite s3://mybucket/litestream

[ -n "$REPLICA_URL" ] || { echo "replica URL required: litestream replicate $DB s3://bucket/prefix"; exit 1; }
litestream replicate "$DB" "$REPLICA_URL"

When it happens

Trigger: Running `litestream replicate /path/to/db` with one positional arg and no -config; intending to supply replicas via config but forgetting the -config flag; shell quoting dropping the second argument.

Common situations: Users migrating from config-file usage who pass just the DB path; scripts where the replica URL variable is empty so only the DB path remains as an argument; quoting mistakes swallowing the URL.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• too many arguments
• too many arguments
• too many arguments
• too many arguments
• start failed: %s

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