RegisterFlagCompletionFunc: flag '%s' does not exist

Error message

RegisterFlagCompletionFunc: flag '%s' does not exist

What it means

Returned by Command.RegisterFlagCompletionFunc when the named flag does not exist on the command's flag set (c.Flag(flagName) returns nil). Registration must happen after the flag is defined; the lookup uses the merged (local + persistent) flag set.

Source

Thrown at completions.go:173

// FixedCompletions can be used to create a completion function which always
// returns the same results.
//
// This method returns a function that satisfies [CompletionFunc]
// It can be used with [Command.RegisterFlagCompletionFunc] and for [Command.ValidArgsFunction].
func FixedCompletions(choices []Completion, directive ShellCompDirective) CompletionFunc {
	return func(cmd *Command, args []string, toComplete string) ([]Completion, ShellCompDirective) {
		return choices, directive
	}
}

// RegisterFlagCompletionFunc should be called to register a function to provide completion for a flag.
//
// You can use pre-defined completion functions such as [FixedCompletions] or [NoFileCompletions],
// or you can define your own.
func (c *Command) RegisterFlagCompletionFunc(flagName string, f CompletionFunc) error {
	flag := c.Flag(flagName)
	if flag == nil {
		return fmt.Errorf("RegisterFlagCompletionFunc: flag '%s' does not exist", flagName)
	}
	flagCompletionMutex.Lock()
	defer flagCompletionMutex.Unlock()

	if _, exists := flagCompletionFunctions[flag]; exists {
		return fmt.Errorf("RegisterFlagCompletionFunc: flag '%s' already registered", flagName)
	}
	flagCompletionFunctions[flag] = f
	return nil
}

// GetFlagCompletionFunc returns the completion function for the given flag of the command, if available.
func (c *Command) GetFlagCompletionFunc(flagName string) (CompletionFunc, bool) {
	flag := c.Flag(flagName)
	if flag == nil {
		return nil, false
	}

View on GitHub (pinned to adbc881390)

Solutions

Define the flag (cmd.Flags().String(...)) BEFORE calling RegisterFlagCompletionFunc.
Spell the flag name exactly as defined (no leading dashes; long name only).
For persistent flags, ensure the parent has added the flag or call c.mergePersistentFlags() path by registering after AddCommand.
Guard the call: check cmd.Flag(name) != nil first, or handle the returned error.

Example fix

// before (flag defined after registration)
cmd.RegisterFlagCompletionFunc("output", completionFn)
cmd.Flags().String("output", "", "output format")

// after
cmd.Flags().String("output", "", "output format")
cmd.RegisterFlagCompletionFunc("output", completionFn)

Defensive patterns

Strategy: validation

Validate before calling

// Guard registration against a missing flag
if cmd.Flag("output") == nil {
    cmd.Flags().String("output", "", "output format")
}
if err := cmd.RegisterFlagCompletionFunc("output", completeOutput); err != nil {
    log.Printf("skip completion: %v", err)
}

Type guard

null

Try / catch

if err := cmd.RegisterFlagCompletionFunc(name, fn); err != nil {
    // non-fatal: completion is optional, log and continue
    log.Printf("flag completion registration failed for %q: %v", name, err)
}

Prevention

Always define a flag before registering its completion.
Centralize flag+completion setup in one builder function to keep ordering correct.
Treat RegisterFlagCompletionFunc errors as non-fatal but logged.

When it happens

Trigger: Calling cmd.RegisterFlagCompletionFunc("output", fn) before defining the --output flag, or with a typo'd flag name, or against a flag defined on a different command. Also fires when a persistent flag is defined on a parent but the child hasn't merged persistent flags at registration time.

Common situations: Order-of-initialization bugs (registering completion in an init() before flags exist), flag renamed but completion call not updated, or copy-paste from another command's setup.

Related errors

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