spf13/cobra · warning

unable to find a command for arguments: %v

Error message

unable to find a command for arguments: %v

What it means

Returned during shell-completion handling (getCompletions) when rootCmd.Find / Traverse cannot resolve the typed args to a real command. This is the completion subsystem telling the shell there is no target command to complete against; the __complete hidden command forwards user input through Find and surfaces its failure here.

Source

Thrown at completions.go:347

	// check if we need to traverse here to parse local flags on parent commands
	if c.Root().TraverseChildren {
		finalCmd, finalArgs, err = c.Root().Traverse(trimmedArgs)
	} else {
		// For Root commands that don't specify any value for their Args fields, when we call
		// Find(), if those Root commands don't have any sub-commands, they will accept arguments.
		// However, because we have added the __complete sub-command in the current code path, the
		// call to Find() -> legacyArgs() will return an error if there are any arguments.
		// To avoid this, we first remove the __complete command to get back to having no sub-commands.
		rootCmd := c.Root()
		if len(rootCmd.Commands()) == 1 {
			rootCmd.RemoveCommand(c)
		}

		finalCmd, finalArgs, err = rootCmd.Find(trimmedArgs)
	}
	if err != nil {
		// Unable to find the real command. E.g., <program> someInvalidCmd <TAB>
		return c, []Completion{}, ShellCompDirectiveDefault, fmt.Errorf("unable to find a command for arguments: %v", trimmedArgs)
	}
	finalCmd.ctx = c.ctx

	// These flags are normally added when `execute()` is called on `finalCmd`,
	// however, when doing completion, we don't call `finalCmd.execute()`.
	// Let's add the --help and --version flag ourselves but only if the finalCmd
	// has not disabled flag parsing; if flag parsing is disabled, it is up to the
	// finalCmd itself to handle the completion of *all* flags.
	if !finalCmd.DisableFlagParsing {
		finalCmd.InitDefaultHelpFlag()
		finalCmd.InitDefaultVersionFlag()
	}

	// Check if we are doing flag value completion before parsing the flags.
	// This is important because if we are completing a flag value, we need to also
	// remove the flag name argument from the list of finalArgs or else the parsing
	// could fail due to an invalid value (incomplete) for the flag.
	flag, finalArgs, toComplete, flagErr := checkIfFlagCompletion(finalCmd, finalArgs, toComplete)

View on GitHub (pinned to adbc881390)

Solutions

  1. Type a valid subcommand (or the prefix of one) before tab-completing; completion works on real command paths.
  2. Ensure all subcommands are AddCommand'd before the completion request is served (avoid lazy registration).
  3. Check the shell completion script is current (regenerate via `<program> completion <shell>`).
  4. This error is usually benign during interactive typing — it simply yields no completions.

Example fix

// before: subcommand registered lazily, missing at completion time
rootCmd.AddCommand(serveCmd) // happens too late

// after: register eagerly during init
func init() { rootCmd.AddCommand(serveCmd) }
Defensive patterns

Strategy: fallback

Validate before calling

// Ensure command tree is fully built before serving completion
func init() {
    rootCmd.AddCommand(serveCmd, buildCmd, deployCmd)
}

Type guard

null

Try / catch

// Completion errors are advisory; the shell simply shows no completions
// No code-level catch needed — these flow through __complete and degrade gracefully.

Prevention

When it happens

Trigger: Typing `<program> invalidSub <TAB>` where invalidSub is not a registered command, or completion invoked mid-token on a path that doesn't exist. With TraverseChildren, a non-command token in the traversal chain produces the same error.

Common situations: Users tab-completing on a misspelled subcommand, completion scripts pointing at a renamed command, or a command tree built lazily so that at completion time the subcommand isn't yet registered.

Related errors

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