PLATFORM_NOT_SUPPORTED cicd build_error ai_generated true

ERROR: failed to solve: platform 'linux/arm64/v8' not supported by the builder instance

ID: cicd/docker-buildx-platform-not-supported

Also available as: JSON · Markdown · 中文
83%Fix Rate
89%Confidence
1Evidence
2024-05-22First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
Docker 24.0 active — — —
Buildx 0.12 active — — —
QEMU 7.2 active — — —
Linux x86_64 host active — — —

Root Cause

Docker Buildx builder does not have the requested platform (e.g., ARM64) enabled or the QEMU emulation is not installed for cross-platform builds.

generic

中文

Docker Buildx构建器没有启用请求的平台（例如ARM64），或未安装用于跨平台构建的QEMU仿真。

Official Documentation

https://docs.docker.com/build/building/multi-platform/

Workarounds

  1. 95% success Install QEMU binfmt support: `docker run --privileged --rm tonistiigi/binfmt --install all`, then create builder: `docker buildx create --name multiarch --driver docker-container --bootstrap` 
    Install QEMU binfmt support: `docker run --privileged --rm tonistiigi/binfmt --install all`, then create builder: `docker buildx create --name multiarch --driver docker-container --bootstrap`
  2. 90% success Use existing multiarch builder: `docker buildx use multiarch && docker buildx inspect --bootstrap` to verify platforms 
    Use existing multiarch builder: `docker buildx use multiarch && docker buildx inspect --bootstrap` to verify platforms
  3. 92% success In CI, add step to setup QEMU: `uses: docker/setup-qemu-action@v3` and `uses: docker/setup-buildx-action@v3` before build 
    In CI, add step to setup QEMU: `uses: docker/setup-qemu-action@v3` and `uses: docker/setup-buildx-action@v3` before build

中文步骤

  1. Install QEMU binfmt support: `docker run --privileged --rm tonistiigi/binfmt --install all`, then create builder: `docker buildx create --name multiarch --driver docker-container --bootstrap`
  2. Use existing multiarch builder: `docker buildx use multiarch && docker buildx inspect --bootstrap` to verify platforms
  3. In CI, add step to setup QEMU: `uses: docker/setup-qemu-action@v3` and `uses: docker/setup-buildx-action@v3` before build

Dead Ends

Common approaches that don't work:

  1. 75% fail

    Default driver doesn't support multi-platform builds at all; fails with different error.

  2. 40% fail

    Avoids the error but defeats the purpose of multi-platform builds; doesn't fix builder configuration.

  3. 55% fail

    Default builder may not include QEMU or ARM emulation; need explicit --driver-opt.