docker/cli · warning · ErrHookTemplateParse

failed to parse hook template

Error message

failed to parse hook template

What it means

ErrHookTemplateParse is a sentinel error declared in cli-plugins/hooks/template.go for failures while parsing or executing a CLI plugin's hook message template. Docker CLI plugins (like buildx or scout) can return 'next steps' hint messages as Go text/template strings with custom functions ({{.Flag}}, {{flag}}, {{arg}}); if template.New(...).Parse or Execute fails on that string, template processing aborts and the hook's messages are dropped.

Source

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

			"arg":  func(_ any, i int) (string, error) { return msgContext.argValue(i) },
		}).Parse(hookTemplate)
		if err != nil {
			return nil, err
		}
		var b bytes.Buffer
		err = tmpl.Execute(&b, msgContext)
		if err != nil {
			return nil, err
		}
		out = b.String()
	}
	if n := strings.Count(out, "\n"); n > maxMessages {
		return nil, fmt.Errorf("hook template contains too many messages (%d): maximum is %d", n, maxMessages)
	}
	return strings.SplitN(out, "\n", maxMessages), nil
}

var ErrHookTemplateParse = errors.New("failed to parse hook template")

// commandInfo provides info about the command for which the hook was invoked.
// It is used for templated hook-messages.
type commandInfo struct {
	cmd *cobra.Command
}

// Name returns the name of the (sub)command for which the hook was invoked.
//
// It's used for backward-compatibility with old templates.
func (c commandInfo) Name() string {
	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 ""

View on GitHub (pinned to e9452d6e78)

Solutions

1. Fix the template string returned by the plugin's hook handler so it is valid Go text/template syntax and only uses supported helpers (.Flag, flag, arg)
2. Validate the template locally with text/template Parse in a unit test before shipping the plugin
3. Upgrade the Docker CLI if the plugin relies on newer template helper functions
4. As a user, disable or update the offending plugin's hooks (remove the plugin hook entry in ~/.docker/config.json) until it is fixed

Example fix

// before (in plugin hook response)
Template: "Try: docker buildx {{ .Missing }"
// after
Template: "Try: docker buildx {{ .Flag }}"

When it happens

Trigger: A plugin's RunHook response contains a Template field with invalid Go template syntax (unclosed {{, unknown function, bad pipeline), or the template references a flag/arg that fails resolution during Execute via the flag()/arg() helper functions. Triggered inside hooks.ParseTemplate, called from cli-plugins/manager/hooks.go after a subcommand invocation matches a plugin's configured hook.

Common situations: Developers writing a CLI plugin with hook support ship a malformed template string; a plugin version mismatch where a newer template syntax (e.g. flag/arg helpers) is used against an older CLI; hand-edited plugin hook config in ~/.docker/config.json producing broken templates.

Related errors

• unexpected hook response type:
• plugin candidate path cannot be empty
• plugin SchemaVersion version cannot be empty
• plugin server is closed
• cannot supply extra formatting options to the pretty templat

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/daf9ce468b1c3f12.json. Report an issue: GitHub.