What causes "level must be between 0 and %d" in benbjohnson/litestream?

Use a level between 0 and litestream.SnapshotLevel (see `litestream ltx -h` for the exact max).

level must be between 0 and %d

Error message

level must be between 0 and %d

What it means

levelVar.Set rejected a numeric level flag because it falls outside the valid compaction level range 0..litestream.SnapshotLevel. Levels below 0 or above the snapshot level do not exist in the LTX level scheme.

Source

Thrown at cmd/litestream/main.go:2204

func (v *levelVar) String() string {
	if *v == levelAll {
		return "all"
	}
	return strconv.Itoa(int(*v))
}

func (v *levelVar) Set(s string) error {
	if s == "all" {
		*v = levelAll
		return nil
	}
	n, err := strconv.Atoi(s)
	if err != nil {
		return fmt.Errorf("invalid level: must be 0-%d or \"all\"", litestream.SnapshotLevel)
	}
	if n < 0 || n > litestream.SnapshotLevel {
		return fmt.Errorf("level must be between 0 and %d", litestream.SnapshotLevel)
	}
	*v = levelVar(n)
	return nil
}

View on GitHub (pinned to 4ed7a308f6)

Solutions

Use a level between 0 and litestream.SnapshotLevel (see `litestream ltx -h` for the exact max).
Use `-level all` when you want every level rather than enumerating high numbers.
Check docs/LTX_FORMAT.md or the level list printed by the command for valid levels.

Example fix

// before
litestream ltx -level 10
// after
litestream ltx -level 3

Defensive patterns

Strategy: validation

Validate before calling

// Clamp level into valid range before invoking the CLI
n, _ := strconv.Atoi(level)
if n < 0 || n > maxSnapshotLevel {
    n = maxSnapshotLevel
}

Try / catch

if err := cmd.Run(); err != nil {
    if strings.Contains(err.Error(), "level must be between") {
        // retry with -level all or a clamped value
    }
}

Prevention

Clamp scripted -level values to 0..SnapshotLevel.
Prefer `-level all` over hardcoding high level numbers in scripts.

When it happens

Trigger: Running `litestream ltx -level 10` (or any integer > SnapshotLevel) or `-level -1`.

Common situations: Guessing the max compaction level after Litestream changed its level set; copying a `-level` value from older docs or other tools.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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