How to fix ERROR: failed to solve: failed to push: unsupported platform in Docker

What this error means

This error indicates that Docker Buildx failed to push an image because the target platform is not supported by either the builder driver, the registry, or the build configuration. The "unsupported platform" message specifically points to a mismatch between what you're trying to build/push and what your current setup can handle. Docker Buildx is an extended build command that supports advanced features like multi-platform builds. However, the default Docker driver that comes with Docker Desktop and Docker Engine only supports building images for your host's native architecture. When you try to build for multiple platforms (like linux/amd64 and linux/arm64 simultaneously), the default driver fails. The solution typically involves switching to a different builder driver (like docker-container) that supports multi-platform builds, installing QEMU for cross-platform emulation, or ensuring your registry supports manifest lists for multi-architecture images.

Typical symptoms

• Build fails with 'ERROR: failed to solve: failed to push: unsupported platform'
• Multi-platform builds fail even though single-platform builds work
• Error appears when using --platform flag with multiple architectures
• CI/CD pipeline fails during multi-arch image push
• Build completes but push step fails with platform error
• Error message: 'multiple platforms feature is currently not supported for docker driver'
• Warning: 'No output specified for docker-container driver'

Common causes

1. Using the default Docker driver which doesn't support multi-platform builds (most common)
2. QEMU emulation not installed for building non-native architectures
3. Buildx builder not properly initialized or bootstrapped
4. Trying to use --load instead of --push with multi-platform builds
5. Docker Desktop containerd feature causing compatibility issues
6. Registry doesn't support manifest lists or multi-architecture images
7. Missing or invalid authentication to container registry
8. Builder created without specifying multi-platform support

How to fix "ERROR: failed to solve: failed to push: unsupported platform"

# Create and switch to a new builder with multi-platform support
docker buildx create --name multiplatform-builder --driver docker-container --use

# Verify the builder is active and supports multiple platforms
docker buildx inspect --bootstrap

# List all builders to confirm
docker buildx ls

# Install QEMU using Docker's official image (works on any Linux/Docker Desktop)
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify QEMU handlers are registered
docker run --privileged --rm tonistiigi/binfmt

# On Ubuntu/Debian, you can also install via apt
sudo apt-get update
sudo apt-get install -y qemu-user-static binfmt-support

# Check available emulation targets
ls /proc/sys/fs/binfmt_misc/qemu-*

# WRONG: --load doesn't work with multi-platform
docker buildx build --platform linux/amd64,linux/arm64 --load -t myimage:latest .
# Error: docker exporter does not currently support exporting manifest lists

# CORRECT: Push directly to registry
docker buildx build --platform linux/amd64,linux/arm64 --push -t myregistry/myimage:latest .

# Or push to local registry for testing
docker run -d -p 5000:5000 --name registry registry:2
docker buildx build --platform linux/amd64,linux/arm64 --push -t localhost:5000/myimage:latest .

# Now you can use --load with multi-platform (on supported setups)
docker buildx build --platform linux/amd64,linux/arm64 --load -t myimage:latest .

# Inspect current builder capabilities
docker buildx inspect --bootstrap

# Expected output includes:
# Platforms: linux/amd64, linux/amd64/v2, linux/arm64, linux/arm/v7, ...

# If platforms are missing, recreate with explicit platform support
docker buildx create --name mybuilder --driver docker-container \
  --platform linux/amd64,linux/arm64,linux/arm/v7 --use

docker buildx inspect --bootstrap

# Login to Docker Hub
docker login

# Login to other registries
docker login ghcr.io
docker login your-private-registry.com

# Verify authentication works
docker buildx build --platform linux/amd64,linux/arm64 \
  --push -t ghcr.io/username/myimage:latest .

name: Build Multi-Platform Image

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

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

      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: username/myimage:latest

Advanced notes

FROM --platform=$BUILDPLATFORM golang:1.21 AS builder

# BUILDPLATFORM = builder's native platform
# TARGETPLATFORM = target platform for the image

ARG TARGETOS TARGETARCH

# Cross-compile for target platform
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /app

FROM alpine:latest
COPY --from=builder /app /app
CMD ["/app"]

# Check what platforms a registry image supports
docker buildx imagetools inspect nginx:latest

# Verify local builder platforms
docker buildx inspect --bootstrap 2>&1 | grep -i platform

# Test platform emulation
docker run --rm --platform linux/arm64 arm64v8/alpine uname -m
# Should output: aarch64

docker run --rm --platform linux/amd64 amd64/alpine uname -m
# Should output: x86_64

# Use registry cache for faster rebuilds
docker buildx build --platform linux/amd64,linux/arm64 \
  --cache-from type=registry,ref=myregistry/myimage:cache \
  --cache-to type=registry,ref=myregistry/myimage:cache,mode=max \
  --push -t myregistry/myimage:latest .

Frequently asked questions

What does "ERROR: failed to solve: failed to push: unsupported platform" mean?

This error indicates that Docker Buildx failed to push an image because the target platform is not supported by either the builder driver, the registry, or the build configuration. The "unsupported platform" message specifically points to a mismatch between what you're trying to build/push and what your current setup can handle. Docker Buildx is an extended build command that supports advanced features like multi-platform builds.

How do I fix "ERROR: failed to solve: failed to push: unsupported platform"?

This error occurs when Docker Buildx attempts to push a multi-platform image but the target registry or driver doesn't support the platform manifest. Common causes include using the default Docker driver (which lacks multi-platform support), missing QEMU emulation for cross-architecture builds, or registry limitations.

What causes "ERROR: failed to solve: failed to push: unsupported platform"?

Using the default Docker driver which doesn't support multi-platform builds (most common) QEMU emulation not installed for building non-native architectures Buildx builder not properly initialized or bootstrapped

Is the "ERROR: failed to solve: failed to push: unsupported platform" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• error exporting cache: failed to export cache

  How to fix 'error exporting cache: failed to export cache' in Docker

  MEDIUM

• ERROR: multiple platforms feature is currently not supported for docker driver

  How to fix 'multiple platforms feature is currently not supported for docker driver' in Docker

  MEDIUM

• failed to solve: failed to load cache key: cache key not found

  How to fix 'failed to load cache key: cache key not found' in Docker

  MEDIUM

• ERROR: failed to solve: failed to load builder

  How to fix 'failed to load builder' in Docker Buildx

  MEDIUM

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 📖
  Docker Docs - Multi-platform builds(Official Docs)
• 📖
  Docker Docs - docker buildx build reference(Official Docs)
• 💬
  Stack Overflow - Cannot build multi-platform images with buildx(Stack Overflow)
• 💬
  Unix StackExchange - Multiple platforms not supported error(Stack Overflow)
• 💬
  Docker Forums - Multiple platforms feature not supported(Stack Overflow)
• 🐙
  GitHub - Buildx platform error handling(GitHub)
• 📝
  100 Common Docker Errors & Solutions