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

- **ID:** `cicd/docker-buildx-platform-not-supported`
- **Domain:** cicd
- **Category:** build_error
- **Error Code:** `PLATFORM_NOT_SUPPORTED`
- **Verification:** ai_generated
- **Fix Rate:** 83%

## 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.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| Docker 24.0 | active | — | — |
| Buildx 0.12 | active | — | — |
| QEMU 7.2 | active | — | — |
| Linux x86_64 host | active | — | — |

## Workarounds

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`** (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`
   ```
2. **Use existing multiarch builder: `docker buildx use multiarch && docker buildx inspect --bootstrap` to verify platforms** (90% success)
   ```
   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** (92% success)
   ```
   In CI, add step to setup QEMU: `uses: docker/setup-qemu-action@v3` and `uses: docker/setup-buildx-action@v3` before build
   ```

## Dead Ends

- **** — Default driver doesn't support multi-platform builds at all; fails with different error. (75% fail)
- **** — Avoids the error but defeats the purpose of multi-platform builds; doesn't fix builder configuration. (40% fail)
- **** — Default builder may not include QEMU or ARM emulation; need explicit --driver-opt. (55% fail)