What causes "args %s has min[%d] > max[%d], not parsing argument" in urfave/cli?

Fix the definition so Min <= Max (e.g. swap or lower Min, or raise Max).

args %s has min[%d] > max[%d], not parsing argument

Error message

args %s has min[%d] > max[%d], not parsing argument

What it means

ArgumentsBase.Parse validates Min <= Max and returns this error when the declared minimum number of values exceeds the maximum. Like the Max==0 case, it is a fail-fast check on the argument's own configuration, reported before any command-line values are consumed.

Source

Thrown at args.go:207

	if a.Min == 0 {
		if a.Max == 1 {
			usageFormat = "[%[1]s]"
		} else {
			usageFormat = "[%[1]s ...]"
		}
	} else {
		usageFormat = "%[1]s [%[1]s ...]"
	}
	return fmt.Sprintf(usageFormat, a.Name)
}

func (a *ArgumentsBase[T, C, VC]) Parse(s []string) ([]string, error) {
	tracef("calling arg%[1] parse with args %[2]", &a.Name, s)
	if a.Max == 0 {
		return s, fmt.Errorf("args %s has max 0, not parsing argument", a.Name)
	}
	if a.Max != -1 && a.Min > a.Max {
		return s, fmt.Errorf("args %s has min[%d] > max[%d], not parsing argument", a.Name, a.Min, a.Max)
	}

	count := 0
	var vc VC
	var t T
	value := vc.Create(a.Value, &t, a.Config)
	a.values = []T{}

	tracef("attempting arg%[1] parse", &a.Name)
	for _, arg := range s {
		if err := value.Set(arg); err != nil {
			return s, fmt.Errorf("invalid value %q for argument %s: %v", arg, a.Name, err)
		}
		tracef("set arg%[1] one value", &a.Name, value.Get().(T))
		a.values = append(a.values, value.Get().(T))
		count++
		if count >= a.Max && a.Max > -1 {
			break

View on GitHub (pinned to 1a4deb4f5a)

Solutions

Fix the definition so Min <= Max (e.g. swap or lower Min, or raise Max).
Use Max: -1 for unbounded arguments when an upper limit is not intended.
Add a sanity check or unit test for dynamically computed Min/Max values.

Example fix

// before
Args: cli.Args{Min: 3, Max: 2}
// after
Args: cli.Args{Min: 2, Max: 3}

Defensive patterns

Strategy: validation

Validate before calling

func argsOK(a cli.Args) bool {
	return a.Max == -1 || a.Min <= a.Max
}
// call on every Args definition before building the command

Try / catch

if err := cmd.Run(ctx, os.Args); err != nil {
	if strings.Contains(err.Error(), "has min[") {
		return fmt.Errorf("argument misconfigured: Min exceeds Max: %w", err)
	}
	return err
}

Prevention

Keep Min <= Max in every Args definition; use Max: -1 for unbounded.
Guard dynamically computed Min/Max with an assertion or unit test.
Re-check Args definitions after refactors that change limits.

When it happens

Trigger: Declaring an argument with Min greater than Max (and Max != -1), e.g. cli.Args{Min: 3, Max: 2}, then parsing any command line for that command.

Common situations: Copy-paste edits of Args definitions, refactors that lowered Max without lowering Min, or computing Min/Max dynamically where Min is derived larger than Max.

Related errors

AI-assisted analysis of urfave/cli@1a4deb4f5a (2026-08-31). Data as JSON: /api/errors/9e37bb3a2a811bcc. Report an issue: GitHub.