benbjohnson/litestream · error

replica URL or config file required

Error message

replica URL or config file required

What it means

Argument validation error from `ValidateCommand.Run`: neither a `--replica-url` nor a `--config` file was supplied, so the command has no replication source to restore from. At least one of the two is required; this is returned right after the source DB check.

Source

Thrown at cmd/litestream-test/validate.go:56

func (c *ValidateCommand) Run(ctx context.Context, args []string) error {
	fs := flag.NewFlagSet("litestream-test validate", flag.ExitOnError)
	fs.StringVar(&c.SourceDB, "source-db", "", "Original database path")
	fs.StringVar(&c.ReplicaURL, "replica-url", "", "Replica URL to validate")
	fs.StringVar(&c.RestoredDB, "restored-db", "", "Path for restored database")
	fs.StringVar(&c.CheckType, "check-type", "quick", "Type of check (quick, integrity, checksum, full)")
	fs.BoolVar(&c.LTXContinuity, "ltx-continuity", false, "Check LTX file continuity")
	fs.StringVar(&c.ConfigPath, "config", "", "Litestream config file path")
	fs.Usage = c.Usage
	if err := fs.Parse(args); err != nil {
		return err
	}

	if c.SourceDB == "" {
		return fmt.Errorf("source database path required")
	}

	if c.ReplicaURL == "" && c.ConfigPath == "" {
		return fmt.Errorf("replica URL or config file required")
	}

	if c.RestoredDB == "" {
		c.RestoredDB = c.SourceDB + ".restored"
	}

	slog.Info("Starting validation",
		"source_db", c.SourceDB,
		"replica_url", c.ReplicaURL,
		"check_type", c.CheckType,
		"ltx_continuity", c.LTXContinuity,
	)

	results := []ValidationResult{}

	if c.LTXContinuity && c.ReplicaURL != "" {
		result := c.validateLTXContinuity(ctx)
		results = append(results, result)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Supply `--replica-url` (e.g. s3://bucket/db or file:///path)
2. Or supply `--config /etc/litestream.yml` describing the replica
3. Verify flag spelling (`--replica-url`, `--config`) — unknown flags may be silently ignored
4. Run `litestream-test validate --help` to confirm flag names

Example fix

// before
litestream-test validate --source-db app.db
// after
litestream-test validate --source-db app.db --replica-url s3://bucket/db

if [ -z "$REPLICA_URL" ] && [ -z "$CONFIG_PATH" ]; then
  echo "provide --replica-url or --config" >&2; exit 2
fi

When it happens

Trigger: Running `litestream-test validate --source-db app.db` with no replica or config; passing `--config` pointing to an empty/incorrect path where parsing silently yields no replica; typo in the flag name so it is not recognized and the value is dropped.

Common situations: Users migrating from older litestream-test versions whose flag names changed; validating with only restored-DB flags; config file present in cwd but not passed explicitly and defaults not pointing at it.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• source database path required
• invalid -timestamp, must specify in ISO 8601 format (e.g. 20
• database path required
• database path required
• delete percentage must be between 0 and 100

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