docker/cli · warning

unexpected hook response type:

Error message

unexpected hook response type: 

What it means

After invoking a plugin hook, the CLI unmarshals the plugin's JSON response into hooks.Response and checks its Type field. hooks.NextSteps is currently the only supported hook response type, so any other numeric type value is rejected with this error and the hook's messages are discarded. It exists to keep forward-compatibility explicit: unknown types fail loudly rather than being misrendered.

Source

Thrown at cli-plugins/manager/hooks.go:96

		}

		resp, err := p.RunHook(ctx, hooks.Request{
			RootCmd:      match,
			Flags:        flags,
			CommandError: cmdErrorMessage,
		})
		if err != nil {
			return nil, false, err
		}

		var message hooks.Response
		if err := json.Unmarshal(resp, &message); err != nil {
			return nil, false, fmt.Errorf("failed to unmarshal hook response (%q): %w", string(resp), err)
		}

		// currently the only hook type
		if message.Type != hooks.NextSteps {
			return nil, false, errors.New("unexpected hook response type: " + strconv.Itoa(int(message.Type)))
		}

		messages, err = hooks.ParseTemplate(message.Template, subCmd)
		if err != nil {
			return nil, false, err
		}

		return messages, true, nil
	}

	for pluginName, pluginCfg := range pluginsCfg {
		messages, ok, err := tryInvokeHook(pluginName, pluginCfg)
		if err != nil {
			// skip misbehaving plugins, but don't halt execution
			logrus.WithFields(logrus.Fields{
				"error":  err,
				"plugin": pluginName,
			}).Debug("Plugin hook invocation failed")

View on GitHub (pinned to e9452d6e78)

Solutions

1. Set Type to hooks.NextSteps in the plugin's hook response struct before marshaling
2. Upgrade the docker CLI so it recognizes the response type the plugin emits
3. Ensure the plugin writes only the JSON response to stdout during the hook call (no stray log output altering the payload)
4. Rebuild the plugin against the same docker/cli cli-plugins/hooks package version as the installed CLI

Example fix

// before (plugin hook handler)
resp := hooks.Response{Template: msg} // Type left as zero value
// after
resp := hooks.Response{Type: hooks.NextSteps, Template: msg}

When it happens

Trigger: A plugin's hook binary (invoked via RunHook) returns JSON whose 'type' field is not the NextSteps constant — e.g. a plugin built against a newer hooks schema that defines additional types, or a plugin that emits a zero/omitted type due to a struct field mismatch, running under an older docker/cli.

Common situations: Version skew between a CLI plugin (buildx, scout, compose) and the docker CLI; a custom plugin author forgetting to set Type: hooks.NextSteps in the response; a plugin printing non-conforming JSON to stdout during the hook invocation.

Related errors

• failed to parse hook template
• plugin candidate path cannot be empty
• plugin SchemaVersion version cannot be empty
• plugin server is closed
• builder prune has been cancelled

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