benbjohnson/litestream · error

source database path required

Error message

source database path required

What it means

Argument validation error from `ValidateCommand.Run` in the litestream-test CLI: the `--source-db` flag was not provided, but it is mandatory — validate needs the source database to compare against a restored replica. Run returns this immediately after flag parsing, before any validation work starts.

Source

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

	ErrorMessage string
	Details      map[string]interface{}
}

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{}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Add `--source-db /path/to/app.db` to the validate command
2. Check `litestream-test validate --help` for required flags
3. If using a config file, still supply `--source-db` (config does not replace it)

Example fix

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

if [ -z "$SOURCE_DB" ] || [ ! -f "$SOURCE_DB" ]; then
  echo "--source-db required and must exist" >&2; exit 2
fi

When it happens

Trigger: Running `litestream-test validate` with only `--replica-url` or `--config` but no `--source-db`; forgetting the flag when invoking from a script; assuming a positional argument sets the source (it does not — flags only).

Common situations: CI scripts templated from the restore command where the source DB was passed positionally; first-time users omitting `--source-db`; config file providing replica info but never the source path.

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

• replica URL or config file 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/9798f7c0b46e3798. Report an issue: GitHub.