docker/compose · error

failed to load Docker Model plugin: %w

Error message

failed to load Docker Model plugin: %w

What it means

The model plugin executable was found by the plugin manager, but it reported a load error (dockerModel.Err). This means the plugin is registered yet broken — a different failure from the plugin being absent.

Source

Thrown at pkg/compose/model.go:90

type modelAPI struct {
	path    string
	env     []string
	prepare func(ctx context.Context, cmd *exec.Cmd) error
	cleanup func()
	version string
}

func (s *composeService) newModelAPI(project *types.Project) (*modelAPI, error) {
	dockerModel, err := manager.GetPlugin("model", s.dockerCli, &cobra.Command{})
	if err != nil {
		if errdefs.IsNotFound(err) {
			return nil, fmt.Errorf("'models' support requires Docker Model plugin")
		}
		return nil, err
	}
	if dockerModel.Err != nil {
		return nil, fmt.Errorf("failed to load Docker Model plugin: %w", dockerModel.Err)
	}
	endpoint, cleanup, err := s.propagateDockerEndpoint()
	if err != nil {
		return nil, err
	}
	return &modelAPI{
		path:    dockerModel.Path,
		version: dockerModel.Version,
		prepare: func(ctx context.Context, cmd *exec.Cmd) error {
			return s.prepareShellOut(ctx, project.Environment, cmd)
		},
		cleanup: cleanup,
		env:     append(project.Environment.Values(), endpoint...),
	}, nil
}

func (m *modelAPI) Close() {
	m.cleanup()

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Run docker model version / docker model ls directly to see the plugin's own failure
2. Reinstall the model plugin (remove and re-add via the plugin manager / reinstall Docker Desktop component)
3. Check the plugin binary is executable and its path intact

if err := runWithModels(ctx, project); err != nil {
    if strings.Contains(err.Error(), "failed to load Docker Model plugin") {
        // reinstall/repair the plugin, then retry once
    }
}

When it happens

Trigger: Plugin discovery succeeds but the plugin metadata/metadata-load step errors: corrupted plugin install, wrong executable permissions, incompatible plugin build.

Common situations: Half-completed plugin installs, plugin updated to a version the installed CLI cannot load, filesystem permission problems on the plugin binary path.

Related errors

• failed to get version of buildx
• 'models' support requires Docker Model plugin
• error checking docker-model status: %w
• error checking available models: %w
• error unmarshalling available models: %w

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/3688032e001dc35f. Report an issue: GitHub.