{"record":{"id":"0b67a09229a0a023","repo":"docker/compose","slug":"models-support-requires-docker-model-plugin","errorCode":null,"errorMessage":"'models' support requires Docker Model plugin","messagePattern":"'models' support requires Docker Model plugin","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/model.go","lineNumber":85,"sourceCode":"\t\t\treturn mdlAPI.ConfigureModel(ctx, config, s.events)\n\t\t})\n\t}\n\treturn eg.Wait()\n}\n\ntype modelAPI struct {\n\tpath    string\n\tenv     []string\n\tprepare func(ctx context.Context, cmd *exec.Cmd) error\n\tcleanup func()\n\tversion string\n}\n\nfunc (s *composeService) newModelAPI(project *types.Project) (*modelAPI, error) {\n\tdockerModel, err := manager.GetPlugin(\"model\", s.dockerCli, &cobra.Command{})\n\tif err != nil {\n\t\tif errdefs.IsNotFound(err) {\n\t\t\treturn nil, fmt.Errorf(\"'models' support requires Docker Model plugin\")\n\t\t}\n\t\treturn nil, err\n\t}\n\tif dockerModel.Err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to load Docker Model plugin: %w\", dockerModel.Err)\n\t}\n\tendpoint, cleanup, err := s.propagateDockerEndpoint()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn &modelAPI{\n\t\tpath:    dockerModel.Path,\n\t\tversion: dockerModel.Version,\n\t\tprepare: func(ctx context.Context, cmd *exec.Cmd) error {\n\t\t\treturn s.prepareShellOut(ctx, project.Environment, cmd)\n\t\t},\n\t\tcleanup: cleanup,\n\t\tenv:     append(project.Environment.Values(), endpoint...),","sourceCodeStart":67,"sourceCodeEnd":103,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/model.go#L67-L103","documentation":"When a compose project uses 'models' (AI model services), compose shells out to the Docker Model plugin located via the CLI plugin manager. If plugin resolution returns NotFound, compose throws this before any model work starts — the plugin simply is not installed on this machine.","triggerScenarios":"A compose file with models/ai service definitions run on a Docker installation without the 'model' CLI plugin (plain Docker Engine without Desktop, or a Linux install where the plugin was never added).","commonSituations":"Developers on Linux Docker Engine trying compose files authored on Docker Desktop; CI images with bare dockerd; users who uninstalled or never installed the model plugin.","solutions":["Install/enable the Docker Model plugin (Docker Desktop includes it; on CLI check `docker model --help` and install the plugin)","Verify with: docker model ls — if that fails, the plugin is missing too","If AI features are unwanted, remove the models section from the compose file"],"exampleFix":"# before (compose.yaml)\nmodels:\n  ai-agent:\n    model: ai/llama3\n\n# after — remove the block when the model plugin is not available\n# (or install the plugin and keep it)","handlingStrategy":"validation","validationCode":"// pre-flight: can we resolve the model plugin?\nif _, err := manager.GetPlugin(\"model\", cli, &cobra.Command{}); errdefs.IsNotFound(err) {\n    return errors.New(\"install the Docker Model plugin or remove 'models' from the compose file\")\n}","typeGuard":null,"tryCatchPattern":"if err := compose.Up(ctx, project, opts); err != nil {\n    if strings.Contains(err.Error(), \"requires Docker Model plugin\") {\n        // guide user to install plugin or strip models section\n    }\n}","preventionTips":["Check `docker model ls` works in the target environment before shipping models in compose files","Gate model-dependent workflows on plugin availability (CI matrix, Docker Desktop detection)"],"tags":["models","plugin","ai","environment"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}