docker/cli · warning

failed to parse hook template: flagValue: no flags found

Error message

failed to parse hook template: flagValue: no flags found

What it means

Returned (wrapped in ErrHookTemplateParse) by commandInfo.flagValue when cobra's Flag(name) returns nil, meaning the named flag does not exist on the command for which the hook was invoked. flagValue is the 'flagValue' template func used in hook message templates.

Solutions

1. Reference only flags that exist on the command that triggers the hook.
2. Fix typos in the flag name inside the template.
3. Update the plugin template after a CLI version renames or removes a flag.

// verify the flag exists on the command before referencing it in a template
if cmd.Flag(flagName) == nil {
    return fmt.Errorf("flag %q not defined on %s", flagName, cmd.Name())
}

if _, err := msgContext.flagValue(name); err != nil {
    // skip or use a default
}

When it happens

Trigger: A hook template referencing {{flagValue "nonexistent"}} for a flag that the current (sub)command does not define.

Common situations: A plugin template written for one command reused against a subcommand lacking that flag, or a typo in the flag name, or a flag renamed/removed in a newer CLI version.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to parse hook template
• hook template contains too many messages
• failed to parse hook template: arg: %dth argument not set
• unexpected hook response type
• failed to unmarshal hook response

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/9b6dbd6117dd527c. Report an issue: GitHub.

Appendix: source

Thrown at cli-plugins/hooks/template.go:79

	return c.command()
}

// command returns the name of the (sub)command for which the hook was invoked.
func (c commandInfo) command() string {
	if c.cmd == nil {
		return ""
	}
	return c.cmd.Name()
}

// flagValue returns the value that was set for the given flag when the hook was invoked.
func (c commandInfo) flagValue(flagName string) (string, error) {
	if c.cmd == nil {
		return "", fmt.Errorf("%w: flagValue: cmd is nil", ErrHookTemplateParse)
	}
	f := c.cmd.Flag(flagName)
	if f == nil {
		return "", fmt.Errorf("%w: flagValue: no flags found", ErrHookTemplateParse)
	}
	return f.Value.String(), nil
}

// argValue returns the value of the nth argument.
func (c commandInfo) argValue(n int) (string, error) {
	if c.cmd == nil {
		return "", fmt.Errorf("%w: arg: cmd is nil", ErrHookTemplateParse)
	}
	flags := c.cmd.Flags()
	v := flags.Arg(n)
	if v == "" && n >= flags.NArg() {
		return "", fmt.Errorf("%w: arg: %dth argument not set", ErrHookTemplateParse, n)
	}
	return v, nil
}

View on GitHub (pinned to 4f84911bfe)