What causes "requires at least %d arg(s), only received %d" in spf13/cobra?

Supply at least n positional arguments.

requires at least %d arg(s), only received %d

Error message

requires at least %d arg(s), only received %d

What it means

Returned by MinimumNArgs(n) when fewer than n positional arguments are supplied. MinimumNArgs returns a PositionalArgs closure you assign to Command.Args; it fires during ValidateArgs at execute time.

Source

Thrown at args.go:90

		if _, ok := seen[arg]; ok {
			return fmt.Errorf("duplicate argument %q for %q", arg, cmd.CommandPath())
		}
		seen[arg] = struct{}{}
	}

	return nil
}

// ArbitraryArgs never returns an error.
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 {

View on GitHub (pinned to adbc881390)

Solutions

Supply at least n positional arguments.
Verify none of the missing tokens were swallowed by a preceding flag that expects a value.
Lower n if the minimum was set too high, or use RangeArgs if the true minimum is flexible.
Check shell quoting: `cmd "a b"` is one arg, not two.

Example fix

// before
cmd.Args = cobra.MinimumNArgs(2)
// `cmd add 1` -> requires at least 2 arg(s), only received 1

// after: `cmd add 1 2`  (or relax to MinimumNArgs(1))

Defensive patterns

Strategy: validation

Validate before calling

// Count positionals (flags already parsed) and warn early
cmd.PersistentPreRunE = func(c *cobra.Command, args []string) error {
    const min = 2
    if len(args) < min {
        return fmt.Errorf("need at least %d operands, got %d", min, len(args))
    }
    return nil
}

Type guard

null

Try / catch

null

Prevention

Use MinimumNArgs consistently for the same conceptual need across commands.
Verify flags that take values use '=' form in docs to avoid operand theft.
Document required operands in the command's Long help.

When it happens

Trigger: Setting `cmd.Args = cobra.MinimumNArgs(2)` and calling `cmd add 1` (one arg). Also fires when optional flags consume tokens the user thought were positional (interspersed parsing), or when shell quoting collapses multiple values into one.

Common situations: Missing required operands, flag values accidentally eating the next positional, or argparse-style expectations that don't match cobra's interspersed default.

Related errors

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