What causes "compose build requires buildx %s or later" in docker/compose?

Upgrade buildx to >= 0.17.0 (download the release binary into ~/.docker/cli-plugins or use docker's install script)

compose build requires buildx %s or later

Error message

compose build requires buildx %s or later

What it means

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.

Source

Thrown at pkg/compose/build_bake.go:442

	return results, nil
}

func (s *composeService) getBuildxPlugin() (*manager.Plugin, error) {
	buildx, err := manager.GetPlugin("buildx", s.dockerCli, &cobra.Command{})
	if err != nil {
		return nil, err
	}

	if buildx.Err != nil {
		return nil, buildx.Err
	}

	if buildx.Version == "" {
		return nil, fmt.Errorf("failed to get version of buildx")
	}

	if versions.LessThan(buildx.Version[1:], buildxMinVersion) {
		return nil, fmt.Errorf("compose build requires buildx %s or later", buildxMinVersion)
	}

	return buildx, nil
}

// makeConsole wraps the provided writer to match [containerd.File] interface if it is of type *streams.Out.
// buildkit's NewDisplay doesn't actually require a [io.Reader], it only uses the [containerd.Console] type to
// benefits from ANSI capabilities, but only does writes.
func makeConsole(out io.Writer) io.Writer {
	if s, ok := out.(*streams.Out); ok {
		return &_console{s}
	}
	return out
}

var _ console.File = &_console{}

type _console struct {

View on GitHub (pinned to ddc4b044b6)

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)

Example fix

# before
$ docker buildx version   # github.com/docker/buildx v0.12.1
$ docker compose build     # compose build requires buildx 0.17.0 or later
# after
$ curl -sSL https://github.com/docker/buildx/releases/latest/download/buildx-v0.17.0.linux-amd64 -o ~/.docker/cli-plugins/docker-buildx
$ chmod +x ~/.docker/cli-plugins/docker-buildx
$ docker compose build

Defensive patterns

Strategy: validation

Validate before calling

// Gate on the minimum version before building:
out, err := exec.Command("docker", "buildx", "version").Output()
if err != nil {
	return err
}
v := strings.TrimSpace(strings.TrimPrefix(strings.Fields(string(out))[len(strings.Fields(string(out)))-1], "v"))
if versions.LessThan(v, "0.17.0") {
	return fmt.Errorf("buildx >= 0.17.0 required, found %s: upgrade the plugin", v)
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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