What causes "accepts at most %d arg(s), received %d" in spf13/cobra?

Reduce positional arguments to at most n.

accepts at most %d arg(s), received %d

Error message

accepts at most %d arg(s), received %d

What it means

Returned by MaximumNArgs(n) when more than n positional arguments are supplied. MaximumNArgs is a PositionalArgs factory assigned to Command.Args; it caps the accepted positional count.

Source

Thrown at args.go:100

func ArbitraryArgs(cmd *Command, args []string) error {
	return nil
}

// MinimumNArgs returns an error if there is not at least N args.
func MinimumNArgs(n int) PositionalArgs {
	return func(cmd *Command, args []string) error {
		if len(args) < n {
			return fmt.Errorf("requires at least %d arg(s), only received %d", n, len(args))
		}
		return nil
	}
}

// MaximumNArgs returns an error if there are more than N args.
func MaximumNArgs(n int) PositionalArgs {
	return func(cmd *Command, args []string) error {
		if len(args) > n {
			return fmt.Errorf("accepts at most %d arg(s), received %d", n, len(args))
		}
		return nil
	}
}

// ExactArgs returns an error if there are not exactly n args.
func ExactArgs(n int) PositionalArgs {
	return func(cmd *Command, args []string) error {
		if len(args) != n {
			return fmt.Errorf("accepts %d arg(s), received %d", n, len(args))
		}
		return nil
	}
}

// RangeArgs returns an error if the number of args is not within the expected range.
func RangeArgs(min int, max int) PositionalArgs {
	return func(cmd *Command, args []string) error {

View on GitHub (pinned to adbc881390)

Solutions

Reduce positional arguments to at most n.
If the command should accept many, raise n or switch to ArbitraryArgs.
Move repeated values behind a repeating flag (StringSlice / StringArray) instead of positionals.

Example fix

// before
cmd.Args = cobra.MaximumNArgs(1)
// `cmd set a b` -> accepts at most 1 arg(s), received 2

// after: `cmd set a`  (or use a slice flag)

Defensive patterns

Strategy: validation

Validate before calling

if len(positionalArgs) > maxN {
    return fmt.Errorf("too many operands (%d > %d); pass extras via --repeat flag", len(positionalArgs), maxN)
}

Type guard

null

Try / catch

null

Prevention

For variadic input, prefer a repeating flag (StringArray/StringSlice) over positionals.
Cap globs in shell scripts before passing to the command.
Pick MaximumNArgs only when a hard upper bound truly exists.

When it happens

Trigger: Setting `cmd.Args = cobra.MaximumNArgs(1)` and calling `cmd set a b c`. Common when a command takes at most one value but the user passes a list, or when glob expansion yields more files than expected.

Common situations: Unbounded shell globs (`cmd *.txt` matching many files), list-vs-scalar confusion, or flags that were expected to repeat but the user passed values as positionals instead.

Related errors

AI-assisted analysis of spf13/cobra@adbc881390 (2026-08-04). Data as JSON: /data/errors/77f653b6f7f02441.json. Report an issue: GitHub.