🐳 Docker Error Guide: 'no builder instance found' docker buildx Failure

Exact Error Message

$ docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest .
ERROR: no builder instance found

Closely related variants report the selected builder is gone or unusable:

ERROR: no builder "mybuilder" found
ERROR: failed to find driver "docker-container": no builder instance found

All of them mean buildx has no active builder it can hand the build to.

What It Means

docker buildx runs builds through a builder instance backed by a BuildKit driver. The default docker driver is limited — it cannot do multi-platform builds or export cache — so multi-arch and advanced builds need a docker-container (or kubernetes/remote) driver builder. When no builder is selected, or the previously selected one was removed or never created, buildx has nowhere to run the build and fails with no builder instance found.

This is an environment setup gap, not a Dockerfile problem. Your build context and image definition are untouched; buildx simply lacks a running backend to execute against.

Common Causes

• No builder was ever created with docker buildx create.
• The active builder was removed (docker buildx rm) or pruned, leaving a dangling selection.
• A fresh machine or CI runner where only the default docker driver exists, which cannot do multi-platform builds.
• DOCKER_CONTEXT/BUILDX_BUILDER points at a builder that does not exist here.
• The buildx CLI plugin is installed but its state directory (~/.docker/buildx) was wiped.
• Attempting --platform with multiple targets on the default driver, which forces the need for a container builder.

Diagnostic Commands

List all builders and see which is selected (marked with *):

docker buildx ls

Confirm the buildx plugin itself is present and its version:

docker buildx version

Inspect the currently selected builder and whether its driver is running:

docker buildx inspect

Check for an override that may be pointing at a missing builder:

echo "BUILDX_BUILDER=$BUILDX_BUILDER DOCKER_CONTEXT=$DOCKER_CONTEXT"

Reproduce the failure with a minimal build:

docker buildx build --platform linux/amd64,linux/arm64 -t test:latest .

Step-by-Step Resolution

1. Check what builders exist. If docker buildx ls shows only the default (docker driver), you need a container-driver builder for multi-platform work:

docker buildx ls

2. Create a new docker-container builder and select it in one step:

docker buildx create --name multiarch --driver docker-container --use

3. Bootstrap the builder so its BuildKit container is pulled and started before you build:

docker buildx inspect --bootstrap

The output should end with Status: running and list the platforms it supports.

4. For multi-platform builds, register QEMU emulators so the container builder can target foreign architectures:

docker run --privileged --rm tonistiigi/binfmt --install all

5. If a stale override is the culprit, clear it and let the newly selected builder take over:

unset BUILDX_BUILDER

6. Re-run the build and confirm it succeeds against the new builder:

docker buildx build --platform linux/amd64,linux/arm64 -t myapp:latest --push .

Pass --push (or --load for single-platform) because the container driver does not put images in the local store automatically.

Prevention

• Bake docker buildx create --name ci --driver docker-container --use into CI runner bootstrap so every job has a real builder before the first build.
• Run docker buildx inspect --bootstrap early in pipelines to fail fast and pull BuildKit before the build step.
• Install QEMU/binfmt once per host so multi-arch builders are always ready, not discovered mid-pipeline.
• Avoid unpinned BUILDX_BUILDER values in shared shell profiles that can reference builders absent on a given machine.
• Keep the buildx plugin updated alongside Docker Engine; a mismatched or missing plugin surfaces as builder confusion.

Related Errors

• docker: 'buildx' is not a docker command — the plugin itself is not installed, a step before builder creation.
• ERROR: Multi-platform build is not supported for the docker driver — you have a builder but it is the wrong (default) driver.
• failed to solve: rpc error: ... connection refused — the builder exists but its BuildKit container is not running; bootstrap it.
• error: failed to push ... : no match for platform in manifest — a registry/manifest issue after a successful multi-arch build.

Frequently Asked Questions

Why does the default docker driver not work for multi-platform builds? The built-in docker driver builds only for the host architecture and cannot export multi-arch manifests. Multi-platform requires a docker-container (or kubernetes) driver builder created with docker buildx create.

What does --use actually do? It sets the newly created builder as the active one for subsequent docker buildx build commands, equivalent to running docker buildx use <name> afterward. Omitting it creates the builder but leaves your selection unchanged.

Do I need to bootstrap every time? No — bootstrapping is idempotent and only starts the BuildKit container if it is not already running. Running --bootstrap in CI is cheap insurance against a cold builder.

How do I set this up reliably in CI? Create and select a docker-container builder as the first pipeline step, then bootstrap it. You can generate a ready-made pipeline snippet from the DevOps AI prompt library at /prompts/?stack=docker.

Why is my multi-platform image missing after a successful build? The container driver does not load into the local image store. Use --push to send it to a registry, or --load for a single-platform build to import it locally. For more build-pipeline fixes, see the Docker guides.