benbjohnson/litestream · error

database path required

Error message

database path required

What it means

The `litestream-test shrink` command aborts before doing any work because the required `-db` flag was not supplied (ShrinkCommand.DB is the empty string). The Run method validates flag input immediately after flag parsing and refuses to proceed without a database path. This is a pure user-input validation error, not a library or environment failure.

Source

Thrown at cmd/litestream-test/shrink.go:38

	Vacuum           bool
	Checkpoint       bool
	CheckpointMode   string
}

func (c *ShrinkCommand) Run(ctx context.Context, args []string) error {
	fs := flag.NewFlagSet("litestream-test shrink", flag.ExitOnError)
	fs.StringVar(&c.DB, "db", "", "Database path (required)")
	fs.Float64Var(&c.DeletePercentage, "delete-percentage", 50, "Percentage of data to delete (0-100)")
	fs.BoolVar(&c.Vacuum, "vacuum", false, "Run VACUUM after deletion")
	fs.BoolVar(&c.Checkpoint, "checkpoint", false, "Run checkpoint after deletion")
	fs.StringVar(&c.CheckpointMode, "checkpoint-mode", "PASSIVE", "Checkpoint mode (PASSIVE, FULL, RESTART, TRUNCATE)")
	fs.Usage = c.Usage
	if err := fs.Parse(args); err != nil {
		return err
	}

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

	if c.DeletePercentage < 0 || c.DeletePercentage > 100 {
		return fmt.Errorf("delete percentage must be between 0 and 100")
	}

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

	slog.Info("Starting database shrink operation",
		"db", c.DB,
		"delete_percentage", c.DeletePercentage,
		"vacuum", c.Vacuum,
		"checkpoint", c.Checkpoint,
	)

	return c.shrinkDatabase(ctx)

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Run the command with the required flag: litestream-test shrink -db /path/to/test.db
2. If a shell script calls it, verify the path variable is non-empty before invoking the command
3. Check `litestream-test shrink` usage output for the exact -db syntax

Example fix

// before
litestream-test shrink -delete-percentage 50
// after
litestream-test shrink -db /tmp/test.db -delete-percentage 50

if dbPath == "" {
    return fmt.Errorf("-db flag is required")
}
// then run:
// litestream-test shrink -db /path/to/test.db ...

When it happens

Trigger: Running `litestream-test shrink` without the `-db PATH` flag, or invoking ShrinkCommand.Run programmatically with args that omit `-db`, leaving c.DB empty after flag.Parse.

Common situations: Developers copy a sample command line and drop the -db flag; scripts interpolate an empty DB path variable (e.g. DB_PATH unset); users pass the path as a positional argument instead of a flag, which Go's flag package ignores.

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

• invalid -timestamp, must specify in ISO 8601 format (e.g. 20
• database path required
• database does not exist: %w
• open database: %w
• ensure test table: %w

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