What causes "invalid argument %q for %q%s" in spf13/cobra?

Use one of the values listed in ValidArgs (check the suggestion text for close matches).

invalid argument %q for %q%s

Error message

invalid argument %q for %q%s

What it means

Returned by OnlyValidArgs when a positional argument is not present in the command's ValidArgs slice. OnlyValidArgs is applied via Command.Args (often combined with MatchAll). The %s suffix appends findSuggestions for close matches against ValidArgs.

Source

Thrown at args.go:61

	if len(args) > 0 {
		return fmt.Errorf("unknown command %q for %q", args[0], cmd.CommandPath())
	}
	return nil
}

// OnlyValidArgs returns an error if there are any positional args that are not in
// the `ValidArgs` field of `Command`
func OnlyValidArgs(cmd *Command, args []string) error {
	if len(cmd.ValidArgs) > 0 {
		// Remove any description that may be included in ValidArgs.
		// A description is following a tab character.
		validArgs := make([]string, 0, len(cmd.ValidArgs))
		for _, v := range cmd.ValidArgs {
			validArgs = append(validArgs, strings.SplitN(v, "\t", 2)[0])
		}
		for _, v := range args {
			if !stringInSlice(v, validArgs) {
				return fmt.Errorf("invalid argument %q for %q%s", v, cmd.CommandPath(), cmd.findSuggestions(args[0]))
			}
		}
	}
	return nil
}

// NoDuplicateArgs returns an error if there are any duplicate positional args.
func NoDuplicateArgs(cmd *Command, args []string) error {
	seen := make(map[string]struct{}, len(args))
	for _, arg := range args {
		if _, ok := seen[arg]; ok {
			return fmt.Errorf("duplicate argument %q for %q", arg, cmd.CommandPath())
		}
		seen[arg] = struct{}{}
	}

	return nil
}

View on GitHub (pinned to adbc881390)

Solutions

Use one of the values listed in ValidArgs (check the suggestion text for close matches).
Add the intended value to cmd.ValidArgs if it should be permitted.
Combine with ExactArgs/MatchAll correctly — ensure OnlyValidArgs is actually the validator you want rather than a stricter one.
Trim/normalize input before validation if whitespace or case is the issue.

Example fix

// before
cmd.ValidArgs = []string{"start", "stop"}
cmd.Args = cobra.OnlyValidArgs
// `cmd pause` -> invalid argument "pause"

// after
cmd.ValidArgs = []string{"start", "stop", "pause"}

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check positional args against ValidArgs before Execute
cmd.PersistentPreRunE = func(c *cobra.Command, args []string) error {
    if len(c.ValidArgs) == 0 { return nil }
    allowed := map[string]struct{}{}
    for _, v := range c.ValidArgs { allowed[strings.SplitN(v, "\t", 2)[0]] = struct{}{} }
    for _, a := range args {
        if _, ok := allowed[a]; !ok {
            return fmt.Errorf("%q is not a valid value; allowed: %v", a, c.ValidArgs)
        }
    }
    return nil
}

Type guard

null

Try / catch

null

Prevention

Keep ValidArgs and the actual handling logic in the same source location so they stay in sync.
Generate ValidArgs from an enum/const list to avoid drift.
Normalize (trim/lowercase) input upstream if case or whitespace matters.

When it happens

Trigger: Setting `cmd.ValidArgs = []string{"start","stop"}` and `cmd.Args = cobra.OnlyValidArgs`, then calling `cmd statr` (typo) or `cmd pause` (not in list). ValidArgs entries may include a tab-delimited description; OnlyValidArgs strips the description before comparing.

Common situations: Typos in allowed values, a value list that wasn't updated when new options were added, case sensitivity surprises (matching is exact), or trailing whitespace in the typed arg.

Related errors

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