How to fix ERROR: failed to solve: failed to load builder in Docker

DockerINTERMEDIATEMEDIUM

The 'failed to solve: failed to load builder' error occurs when Docker Buildx cannot find or initialize a valid builder instance. This typically happens due to missing or broken buildx plugin installation, misconfigured builders, or WSL/Docker Desktop integration issues.

What this error means

The "failed to solve: failed to load builder" error in Docker Buildx indicates that the build process cannot locate or initialize the specified builder instance. Buildx is Docker's extended build capability that uses BuildKit for advanced features like multi-platform builds and improved caching. When you run a buildx command, Docker attempts to load a builder - either the default one or a named builder you've created. If the builder configuration is corrupted, the buildx plugin is missing or broken, or there are environment issues (especially common in WSL setups), this error appears. This error is particularly common after uninstalling Docker Desktop on Windows while still using Docker in WSL, as the uninstallation can leave behind broken symlinks to Docker Desktop's buildx plugin. It can also occur when the buildx binary is missing from the expected plugin locations or when attempting to use a builder that was never properly created.

How to fix "ERROR: failed to solve: failed to load builder"

1Check if buildx plugin is installed correctly

First, verify that the buildx plugin is properly installed and accessible:

bash

# Check buildx version
docker buildx version

# List available builders
docker buildx ls

If these commands fail or show errors, the buildx plugin may be missing or broken.

2Check for broken symlinks (WSL users)

If you previously used Docker Desktop on Windows and uninstalled it, broken symlinks may remain. Check the CLI plugins directory:

bash

# Check for broken symlinks
ls -la /usr/local/lib/docker/cli-plugins/

# If you see broken links pointing to /mnt/wsl/docker-desktop/...
# they need to be removed

If you see symlinks pointing to non-existent Docker Desktop paths (like /mnt/wsl/docker-desktop/cli-tools/...), these need to be cleaned up.

3Remove broken Docker installation files

If you found broken symlinks, remove them and reinstall the buildx plugin:

bash

# Remove the broken symlinks/files
sudo rm -rf /usr/local/lib/docker/

# Update package lists
sudo apt update

This clears out any corrupted Docker plugin files so you can install fresh ones.

4Install or reinstall the docker-buildx-plugin

Install the buildx plugin from your package manager:

bash

# For Debian/Ubuntu
sudo apt install -y docker-buildx-plugin

# If on Ubuntu 22.04+, you might need:
sudo apt install -y docker-buildx

# For Fedora/RHEL
sudo dnf install -y docker-buildx-plugin

# Verify installation
docker buildx version

The package name may vary slightly between distributions.

5Create and configure a new builder

After installing buildx, create a new builder instance:

bash

# Create a new builder with docker-container driver
docker buildx create --name mybuilder --driver docker-container --use

# Bootstrap the builder (downloads BuildKit image and starts container)
docker buildx inspect --bootstrap mybuilder

# Verify the builder is active
docker buildx ls

The --bootstrap flag ensures the builder is fully initialized before use.

6Ensure Docker Desktop is running (WSL users)

If you're using WSL with Docker Desktop integration, make sure Docker Desktop is actually running on Windows:

1. Check the Windows system tray for the Docker Desktop icon
2. If not running, start Docker Desktop from the Start menu
3. Wait for it to fully start (the icon should stop animating)
4. Then try your buildx command again in WSL

bash

# After starting Docker Desktop, verify connection
docker info
docker buildx ls

7Reset buildx configuration

If the buildx configuration is corrupted, you can reset it:

bash

# Remove all buildx builders
docker buildx rm --all-inactive

# Remove buildx config directory (creates fresh on next use)
rm -rf ~/.docker/buildx/

# Recreate the default builder
docker buildx create --name default --driver docker-container --use
docker buildx inspect --bootstrap

This gives you a clean slate for buildx configuration.

8Manual buildx installation (alternative method)

If package manager installation doesn't work, you can install buildx manually:

bash

# Download the latest buildx binary (check GitHub for latest version)
BUILDX_VERSION=$(curl -s https://api.github.com/repos/docker/buildx/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
wget https://github.com/docker/buildx/releases/download/${BUILDX_VERSION}/buildx-${BUILDX_VERSION}.linux-amd64

# Create plugin directory and install
mkdir -p ~/.docker/cli-plugins/
mv buildx-${BUILDX_VERSION}.linux-amd64 ~/.docker/cli-plugins/docker-buildx
chmod +x ~/.docker/cli-plugins/docker-buildx

# Verify installation
docker buildx version

Adjust the architecture in the download URL if you're on ARM (use linux-arm64).

Advanced notes

### Understanding Buildx Drivers

Docker Buildx supports multiple drivers, each with different capabilities:

- docker: Uses the built-in Docker daemon builder. Limited features but no additional setup. Doesn't support multi-platform builds.
- docker-container: Runs BuildKit in a container. Supports multi-platform builds and advanced caching. This is the recommended driver for most use cases.
- kubernetes: Runs BuildKit pods on Kubernetes. Useful for distributed builds.
- remote: Connects to a remote BuildKit daemon. For custom BuildKit deployments.

When you see "failed to load builder", it usually means the docker-container driver's container is missing or the docker driver is not properly configured.

### Multi-Platform Build Setup

For cross-platform builds (e.g., building ARM images on x86), you need QEMU emulation:

bash

# Install QEMU for multi-platform support
docker run --privileged --rm tonistiigi/binfmt --install all

# Create a builder with multi-platform support
docker buildx create --name multiarch --driver docker-container --platform linux/amd64,linux/arm64 --use

# Build for multiple platforms
docker buildx build --platform linux/amd64,linux/arm64 -t myimage:latest .

### CI/CD Considerations

In CI/CD environments (GitHub Actions, GitLab CI, etc.), you typically need to:

1. Install the buildx plugin
2. Create a builder instance in each job
3. Use caching to speed up builds

Example for GitHub Actions:

yaml

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3

- name: Build and push
  uses: docker/build-push-action@v5
  with:
    context: .
    platforms: linux/amd64,linux/arm64
    push: true
    tags: user/app:latest

### WSL-Specific Issues

After removing Docker Desktop, WSL may retain configuration pointing to Docker Desktop paths. Beyond removing symlinks, you may also need to:

bash

# Check if Docker context is pointing to Docker Desktop
docker context ls

# If using a Docker Desktop context, switch to default
docker context use default

If you're running Docker natively in WSL (not via Docker Desktop), ensure the Docker daemon is running:

bash

sudo service docker start
# Or with systemd
sudo systemctl start docker

How to fix ERROR: failed to solve: failed to load builder in Docker

What this error means

Typical symptoms

Common causes

How to fix "ERROR: failed to solve: failed to load builder"

Advanced notes

Related errors

Official resources & further reading