spf13/cobra · error

unknown command %q for %q%s

Error message

unknown command %q for %q%s

What it means

Thrown by legacyArgs (cobra's default Args validator) when a root command that HAS subcommands receives positional arguments that don't match any subcommand. Cobra treats the first positional arg as a candidate subcommand name; if no child matches, it reports the arg as an 'unknown command' and appends suggestion text (the %s is findSuggestions output, e.g. 'Did you mean this?'). This is the implicit validation applied when you do not set Command.Args.

Source

Thrown at args.go:36

	"fmt"
	"strings"
)

type PositionalArgs func(cmd *Command, args []string) error

// legacyArgs validation has the following behaviour:
// - root commands with no subcommands can take arbitrary arguments
// - root commands with subcommands will do subcommand validity checking
// - subcommands will always accept arbitrary arguments
func legacyArgs(cmd *Command, args []string) error {
	// no subcommand, always take args
	if !cmd.HasSubCommands() {
		return nil
	}

	// root command with subcommands, do subcommand checking.
	if !cmd.HasParent() && len(args) > 0 {
		return fmt.Errorf("unknown command %q for %q%s", args[0], cmd.CommandPath(), cmd.findSuggestions(args[0]))
	}
	return nil
}

// NoArgs returns an error if any args are included.
func NoArgs(cmd *Command, args []string) error {
	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.

View on GitHub (pinned to adbc881390)

Solutions

1. Check the spelled subcommand against the output of `<program> help` or the suggestions Cobra prints (the %s portion lists close matches).
2. If the root should accept arbitrary positional args even though it has subcommands, set rootCmd.Args = cobra.ArbitraryArgs (or a custom PositionalArgs) to bypass legacyArgs.
3. Register the intended command as a child via rootCmd.AddCommand(&subCmd) if it was supposed to exist.
4. If you want unknown subcommand input to route to the root, set the root's Args field explicitly and consider TraverseChildren.

Example fix

// before: root has subcommands, default Args validator
rootCmd := &cobra.Command{Use: "app"}
rootCmd.AddCommand(serveCmd)
// `app srve` -> unknown command "srve"

// after: accept arbitrary args at root, or fix the typo
rootCmd.Args = cobra.ArbitraryArgs

// Before Execute, confirm the first positional resolves to a child
func resolveSubcommand(root *cobra.Command, args []string) error {
    if !root.HasSubCommands() || len(args) == 0 {
        return nil
    }
    target, _, err := root.Find(args)
    if err != nil || target == root && len(target.Commands()) > 0 {
        names := []string{}
        for _, c := range root.Commands() { if c.IsAvailableCommand() { names = append(names, c.Name()) } }
        return fmt.Errorf("no subcommand %q; choose from %v", args[0], names)
    }
    return nil
}

null

null

When it happens

Trigger: Running `rootCmd foobar` where rootCmd has subcommands registered via AddCommand but 'foobar' is not one of them. Also triggered by typos in subcommand names, or by passing a flag-like token after `--` to a root that has children (legacyArgs still checks args[0]). Does NOT fire if the command has no subcommands, or if the command is itself a subcommand (HasParent).

Common situations: Misspelling a subcommand (`gti status` style typo), renamed subcommands after a library upgrade, hidden/deprecated commands the user expects to exist, or a root command that the developer assumed would accept arbitrary args but actually has children registered.

Related errors

• unknown command %q for %q
• invalid argument %q for %q%s
• duplicate argument %q for %q
• requires at least %d arg(s), only received %d
• accepts at most %d arg(s), received %d

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