What causes "database path required" in benbjohnson/litestream?

Pass the -db flag with the database path: `litestream-test load -db /path/to/db.sqlite`

database path required

Error message

database path required

What it means

The litestream-test 'load' command requires a target SQLite database path, supplied via the -db flag. Run returns this error when flag parsing succeeded but the -db value is still the empty string (flag never provided). It's a plain input validation error before any file or database access.

Source

Thrown at cmd/litestream-test/load.go:57

	mu         sync.Mutex
}

func (c *LoadCommand) Run(ctx context.Context, args []string) error {
	fs := flag.NewFlagSet("litestream-test load", flag.ExitOnError)
	fs.StringVar(&c.DB, "db", "", "Database path (required)")
	fs.IntVar(&c.WriteRate, "write-rate", 100, "Writes per second")
	fs.DurationVar(&c.Duration, "duration", 1*time.Minute, "How long to run")
	fs.StringVar(&c.Pattern, "pattern", "constant", "Write pattern (constant, burst, random, wave)")
	fs.IntVar(&c.PayloadSize, "payload-size", 1024, "Size of each write operation in bytes")
	fs.Float64Var(&c.ReadRatio, "read-ratio", 0.2, "Read/write ratio (0.0-1.0)")
	fs.IntVar(&c.Workers, "workers", 1, "Number of concurrent workers")
	fs.Usage = c.Usage
	if err := fs.Parse(args); err != nil {
		return err
	}

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

	if _, err := os.Stat(c.DB); err != nil {
		return fmt.Errorf("database does not exist: %w", err)
	}

	slog.Info("Starting load generation",
		"db", c.DB,
		"write_rate", c.WriteRate,
		"duration", c.Duration,
		"pattern", c.Pattern,
		"payload_size", c.PayloadSize,
		"read_ratio", c.ReadRatio,
		"workers", c.Workers,
	)

	return c.generateLoad(ctx)
}

View on GitHub (pinned to 4ed7a308f6)

Solutions

Pass the -db flag with the database path: `litestream-test load -db /path/to/db.sqlite`
If scripting, set the flag from a variable and fail fast when the variable is empty
Run `litestream-test load -h` to see the exact flag names and defaults

Example fix

// before
litestream-test load -write-rate 100
// after
litestream-test load -db /data/app.db -write-rate 100

Defensive patterns

Strategy: validation

Validate before calling

// shell
if [ -z "$DB_PATH" ]; then echo "-db is required"; exit 2; fi
litestream-test load -db "$DB_PATH" "$@"

Try / catch

// Go (calling Run programmatically)
if err := cmd.Run(ctx, args); err != nil {
	if strings.Contains(err.Error(), "database path required") {
		return fmt.Errorf("load: usage: litestream-test load -db <path> [flags]")
	}
	return err
}

Prevention

Always pass -db explicitly; there is no default database path
Use a wrapper script that injects -db from config/env
Check `litestream-test load -h` when unsure of flag names
Validate the DB file exists before invoking to also avoid the follow-on 'database does not exist' error

When it happens

Trigger: Running 'litestream-test load' (or another subcommand reusing LoadCommand) without the -db flag, e.g. `litestream-test load -write-rate 100`, so c.DB remains "" after fs.Parse.

Common situations: Forgetting -db when scripting load tests; assuming a positional argument is used instead of the -db flag; copy-pasting examples that omit the flag.

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

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