{"record":{"id":"07dd064aed1f9162","repo":"docker/compose","slug":"compose-build-requires-buildx-s-or-later","errorCode":null,"errorMessage":"compose build requires buildx %s or later","messagePattern":"compose build requires buildx (.+?) or later","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/build_bake.go","lineNumber":442,"sourceCode":"\treturn results, nil\n}\n\nfunc (s *composeService) getBuildxPlugin() (*manager.Plugin, error) {\n\tbuildx, err := manager.GetPlugin(\"buildx\", s.dockerCli, &cobra.Command{})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tif buildx.Err != nil {\n\t\treturn nil, buildx.Err\n\t}\n\n\tif buildx.Version == \"\" {\n\t\treturn nil, fmt.Errorf(\"failed to get version of buildx\")\n\t}\n\n\tif versions.LessThan(buildx.Version[1:], buildxMinVersion) {\n\t\treturn nil, fmt.Errorf(\"compose build requires buildx %s or later\", buildxMinVersion)\n\t}\n\n\treturn buildx, nil\n}\n\n// makeConsole wraps the provided writer to match [containerd.File] interface if it is of type *streams.Out.\n// buildkit's NewDisplay doesn't actually require a [io.Reader], it only uses the [containerd.Console] type to\n// benefits from ANSI capabilities, but only does writes.\nfunc makeConsole(out io.Writer) io.Writer {\n\tif s, ok := out.(*streams.Out); ok {\n\t\treturn &_console{s}\n\t}\n\treturn out\n}\n\nvar _ console.File = &_console{}\n\ntype _console struct {","sourceCodeStart":424,"sourceCodeEnd":460,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/build_bake.go#L424-L460","documentation":"The bake build path requires modern buildx features (metadata files, bake targets), so compose compares the resolved plugin version against buildxMinVersion (0.17.0 in this tree) using versions.LessThan on the version with its leading 'v' stripped. When the installed plugin is older than the minimum, this error is returned telling the user exactly which floor applies. It is a deliberate compatibility gate, not a runtime failure.","triggerScenarios":"docker compose build (or up with build) with COMPOSE_BAKE enabled (default on capable hosts) while the installed buildx plugin is older than 0.17.0 — common on long-lived hosts, base images, or distributions shipping stale docker CLI plugin packages.","commonSituations":"Old Docker Engine bundles with legacy buildx; apt/yum-installed docker-cli whose plugins lag; CI base images pinned to old versions; systems where a global old buildx in /usr/libexec shadows a newer user install.","solutions":["Upgrade buildx to >= 0.17.0 (download the release binary into ~/.docker/cli-plugins or use docker's install script)","Verify with docker buildx version and ensure PATH/plugin dirs resolve the new binary first","As a stopgap, set COMPOSE_BAKE=false to use the classic builder (losing buildx features)"],"exampleFix":"# before\n$ docker buildx version   # github.com/docker/buildx v0.12.1\n$ docker compose build     # compose build requires buildx 0.17.0 or later\n# after\n$ curl -sSL https://github.com/docker/buildx/releases/latest/download/buildx-v0.17.0.linux-amd64 -o ~/.docker/cli-plugins/docker-buildx\n$ chmod +x ~/.docker/cli-plugins/docker-buildx\n$ docker compose build\n","handlingStrategy":"validation","validationCode":"// Gate on the minimum version before building:\nout, err := exec.Command(\"docker\", \"buildx\", \"version\").Output()\nif err != nil {\n\treturn err\n}\nv := strings.TrimSpace(strings.TrimPrefix(strings.Fields(string(out))[len(strings.Fields(string(out)))-1], \"v\"))\nif versions.LessThan(v, \"0.17.0\") {\n\treturn fmt.Errorf(\"buildx >= 0.17.0 required, found %s: upgrade the plugin\", v)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install/upgrade buildx as part of environment bootstrap (script or Dockerfile step)","Pin CI base images that bundle current docker CLI + buildx plugins","Alert on buildx age in environment doctor checks"],"tags":["buildx","version","compatibility","build"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}