docker/cli · error

%w %s

Error message

%w

%s

What it means

Returned by newBuilderError() when loading the builder plugin (buildx) produced an error that is NOT a 'not found' error (errdefs.IsNotFound is false). It wraps the plugin load error (%w) and appends a human-readable message (%s — buildxMissingError/bakeMissingError) explaining the fix. This indicates buildx exists but is broken, not merely absent.

Solutions

1. Reinstall/repair the buildx plugin: `docker buildx install` or download a matching version from the official release.
2. Check the wrapped %w error for the concrete load failure (exec format, permission, manifest parse).
3. Verify the plugin binary is executable and matches your platform (`file $(which docker-buildx)`).
4. As a temporary workaround, set DOCKER_BUILDKIT=0 to use the legacy builder (note the deprecation warning).

Example fix

// before
$ DOCKER_BUILDKIT=1 docker build .
ERROR: BuildKit is enabled but the buildx component is missing or broken.
<wrapped load error>

// after — reinstall buildx matching this CLI version
$ docker buildx install
$ docker build .

// Check buildx plugin health before relying on it
func buildxHealthy() error {
    out, err := exec.Command("docker", "buildx", "version").CombinedOutput()
    if err != nil { return fmt.Errorf("buildx plugin broken: %s", out) }
    return nil
}

// Fall back to the legacy builder if buildx is broken and the user opted in
if err := buildxHealthy(); err != nil {
    if os.Getenv("DOCKER_BUILDKIT_FALLBACK") == "1" {
        os.Setenv("DOCKER_BUILDKIT", "0") // legacy builder (deprecated)
    }
}

When it happens

Trigger: Running `docker build`/`docker bake` with DOCKER_BUILDKIT=1 (or a builder alias) where the buildx plugin binary is present but fails to load — corrupt binary, version mismatch, missing shared library, permission denied on the plugin executable, or the plugin returned a malformed manifest.

Common situations: Partial/failed buildx installation; OS upgrade breaking dynamic library dependencies of the plugin; mixing plugin versions with the CLI; corrupted plugin binary on disk.

Related errors

• DOCKER_BUILDKIT environment variable expects boolean value
• context must be a directory
• the plugin must be disabled before upgrading
• plugin upgrade has been cancelled
• DOCKER_BUILDKIT environment variable expects boolean value

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/6d6f39837b181950. Report an issue: GitHub.

Appendix: source

Thrown at cmd/docker/builder.go:44

	buildkitDisabledWarning = `DEPRECATED: The legacy builder is deprecated and will be removed in a future release.
            BuildKit is currently disabled; enable it by removing the DOCKER_BUILDKIT=0
            environment-variable.`

	buildxMissingError = `ERROR: BuildKit is enabled but the buildx component is missing or broken.
       Install the buildx component to build images with BuildKit:
       https://docs.docker.com/go/buildx/`

	bakeMissingError = `ERROR: docker bake requires the buildx component but it is missing or broken.
       Install the buildx component to use bake:
       https://docs.docker.com/go/buildx/`
)

func newBuilderError(errorMsg string, pluginLoadErr error) error {
	if errdefs.IsNotFound(pluginLoadErr) {
		return errors.New(errorMsg)
	}
	if pluginLoadErr != nil {
		return fmt.Errorf("%w\n\n%s", pluginLoadErr, errorMsg)
	}
	return errors.New(errorMsg)
}

//nolint:gocyclo
func processBuilder(dockerCli command.Cli, cmd *cobra.Command, args, osargs []string) ([]string, []string, []string, error) {
	var buildKitDisabled, useBuilder, useAlias bool
	var envs []string

	// check DOCKER_BUILDKIT env var is not empty
	// if it is assume we want to use the builder component
	if v := os.Getenv("DOCKER_BUILDKIT"); v != "" {
		enabled, err := strconv.ParseBool(v)
		if err != nil {
			return args, osargs, nil, fmt.Errorf("DOCKER_BUILDKIT environment variable expects boolean value: %w", err)
		}
		if !enabled {
			buildKitDisabled = true

View on GitHub (pinned to 4f84911bfe)