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

DockerINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 259 views

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.

Quick fix

Fixes ERROR: failed to solve: failed to load builder

# Check buildx version
docker buildx version

# List available builders
docker buildx ls
  1. Check if buildx plugin is installed correctly
  2. Check for broken symlinks (WSL users)
  3. Remove broken Docker installation files
  4. Install or reinstall the docker-buildx-plugin
docker — error
# Check buildx version
docker buildx version
# List available builders
docker buildx ls
ERROR: failed to solve: failed to load builder

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.

Typical symptoms

  • Docker buildx build commands fail with 'failed to load builder' error
  • Error appears after uninstalling Docker Desktop on Windows while using WSL
  • Commands like 'docker buildx ls' show empty or error output
  • Multi-platform builds fail to start
  • Regular 'docker build' works but 'docker buildx build' fails
  • Error occurs in CI/CD pipelines using buildx for cross-platform builds
  • 'docker buildx version' returns an error or is not recognized

Common causes

  1. Docker buildx plugin is not installed or is missing from the CLI plugins directory
  2. Broken symlinks to Docker Desktop's buildx after uninstalling Docker Desktop (common on WSL)
  3. The specified builder does not exist or was never created
  4. Corrupted buildx configuration in ~/.docker/buildx/
  5. Docker Desktop is not running (for WSL users relying on Docker Desktop integration)
  6. Incompatible or outdated buildx plugin version
  7. Missing or misconfigured BuildKit container for docker-container driver
  8. Permission issues accessing buildx plugin or configuration files

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

Frequently asked questions

What does "ERROR: failed to solve: failed to load builder" mean?
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.
How do I fix "ERROR: failed to solve: failed to load builder"?
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 causes "ERROR: failed to solve: failed to load builder"?
Docker buildx plugin is not installed or is missing from the CLI plugins directory Broken symlinks to Docker Desktop's buildx after uninstalling Docker Desktop (common on WSL) The specified builder does not exist or was never created
Is the "ERROR: failed to solve: failed to load builder" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading