🐳 Docker Error Guide: 'the buildx builder container is not running' BuildKit Failure

Exact Error Message

$ docker buildx build -t myapp:latest .
ERROR: failed to solve: failed to connect to the builder: could not start buildkit:
the buildx builder container "buildx_buildkit_mybuilder0" is not running

Closely related variants from the same builder problem include:

ERROR: no builder "mybuilder" found

ERROR: failed to solve: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

The core issue is that the docker-container driver’s backing container, which actually runs BuildKit, is stopped, missing, or unreachable.

What It Means

Docker Buildx can use different drivers. The default docker driver builds inside the daemon, but the docker-container driver (created with docker buildx create) runs BuildKit inside its own dedicated container. That container is where multi-platform builds, advanced caching, and the newer BuildKit features actually execute.

When you see the buildx builder container is not running, Buildx found the builder definition but its backing container is stopped or was removed, for example after a host reboot or a docker system prune. Buildx cannot connect to a BuildKit endpoint that has no live container, so the build fails before any build step runs.

Common Causes

• The host rebooted and the buildx_buildkit_* container did not restart.
• docker system prune or docker container prune removed the stopped builder container.
• The builder was created but never bootstrapped, so its container was never started.
• The Docker daemon was restarted and the builder container stayed stopped.
• A stale or corrupted builder instance remains in docker buildx ls after a failed create.
• The builder was created against a different Docker context than the one currently active.

Diagnostic Commands

List all builders and their status; look for inactive or error:

docker buildx ls

Check whether the backing BuildKit container actually exists and is running:

docker ps -a --filter name=buildx_buildkit

Inspect the specific builder for its driver and endpoint:

docker buildx inspect mybuilder

Confirm the Docker daemon itself is reachable:

docker info --format '{{.ServerVersion}}'

Step-by-Step Resolution

1. Confirm the daemon is up first. If docker info fails, start Docker before touching Buildx; a dead daemon produces the same symptom for a different reason.

2. Try bootstrapping the existing builder, which starts its container if it exists but is stopped:

docker buildx inspect mybuilder --bootstrap

3. If the backing container is present but stopped, start it directly:

docker start buildx_buildkit_mybuilder0

4. Select the builder as active and verify it reports running:

docker buildx use mybuilder
docker buildx ls

5. If the container was pruned or the builder is corrupted, remove the stale instance and recreate it cleanly:

docker buildx rm mybuilder
docker buildx create --name mybuilder --driver docker-container --bootstrap --use

6. As a quick fallback for a simple build, switch to the default in-daemon driver, which needs no separate container:

docker buildx use default
docker buildx build -t myapp:latest .

7. Re-run the original build and confirm it proceeds past the connection step:

docker buildx build -t myapp:latest .

[+] Building 12.4s (9/9) FINISHED
 => => writing image sha256:...

Prevention

• Bootstrap the builder as part of your build script (docker buildx inspect <name> --bootstrap) so a stopped container is started automatically before every run.
• Avoid blanket docker system prune -a on build hosts, or exclude the buildx_buildkit_* containers, since pruning them silently breaks the builder.
• In CI, create the builder fresh in each job rather than assuming a persistent one survives between runs or reboots.
• Pin builds to an explicit builder with --builder <name> so you do not accidentally target a stale or wrong-context instance.
• After host reboots, add a startup step that runs docker buildx inspect --bootstrap so multi-platform builds are ready without manual intervention.
• Keep one builder per Docker context and name it clearly; builders created in one context are not visible in another.

Related Errors

• no builder "<name>" found — the builder definition itself is gone, not just its container.
• Cannot connect to the Docker daemon — the daemon is down, so no driver can work.
• failed to solve: failed to load cache key — BuildKit is running but a cache backend is unreachable.
• multiple platforms feature is currently not supported for docker driver — the default driver cannot do multi-platform; you need the container driver.

Frequently Asked Questions

What is the difference between the docker and docker-container drivers? The docker driver builds inside the Docker daemon and needs no extra container. The docker-container driver runs BuildKit in its own container, enabling multi-platform builds and richer caching, but that container must be running for builds to work.

Why did my builder stop working after a reboot? The buildx_buildkit_* container does not have a restart policy that survives a host reboot by default, so it stays stopped. Running docker buildx inspect <name> --bootstrap starts it again.

Did docker system prune break my builder? Very likely. A broad prune removes stopped containers, including the builder’s backing container. Recreate it with docker buildx create ... --bootstrap, and be more selective with prune on build hosts.

How do I recover without recreating the builder? Run docker start buildx_buildkit_<name>0 if the container still exists, then docker buildx use <name>. Only recreate when the container was removed entirely or the instance is corrupted.

Where can I find more build troubleshooting help? Generate builder setup and fix commands for your pipeline with the DevOps AI prompt library, and see more Docker guides.