What causes "args %s has max 0, not parsing argument" in urfave/cli?

Set Max to the maximum number of values you accept, or -1 for unlimited.

args %s has max 0, not parsing argument

Error message

args %s has max 0, not parsing argument

What it means

ArgumentsBase.Parse rejects an argument definition whose Max slice length is 0, returning this error. Max==0 means the argument could never accept any values, which is almost certainly a mis-declared argument, so parsing fails fast instead of silently consuming nothing.

Source

Thrown at args.go:204

	}

	usageFormat := ""
	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))

View on GitHub (pinned to 1a4deb4f5a)

Solutions

Set Max to the maximum number of values you accept, or -1 for unlimited.
Use the helper constructors (e.g. cli.Args, cli.ArbitraryArgs) instead of hand-built structs so Max is initialized correctly.
If the argument should be removed, delete it rather than leaving Max: 0.

Example fix

// before
Args: cli.Args{Min: 1, Max: 0}
// after
Args: cli.Args{Min: 1, Max: 1}

Defensive patterns

Strategy: validation

Validate before calling

func argsOK(a cli.Args) bool {
	return a.Max != 0 && (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 max 0") {
		return fmt.Errorf("argument misconfigured: Max must be >0 or -1: %w", err)
	}
	return err
}

Prevention

Never leave Max at its zero value; set an explicit positive number or -1.
Prefer library constructors (cli.Args, cli.ArbitraryArgs) over hand-built structs.
Add a startup test asserting every command's Args passes the arity checks.

When it happens

Trigger: Defining a positional argument (e.g. cli.Args{Min: 0, Max: 0} or an ArgumentsBase with Max left at 0) and then invoking command parsing with any arguments present.

Common situations: Constructing an ArgumentsBase/Args struct by hand and forgetting to set Max (zero value is 0, not the -1 unlimited sentinel), or upgrading library versions where the zero-value semantics differ.

Related errors

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