Victor's room

Quick Summary: The error no matching manifest for linux/arm64 in the manifest list entries (or linux/arm64/v8) occurs when pulling or building a Docker container on an ARM-based host (such as Apple Silicon M1/M2/M3/M4 or AWS Graviton) where the target registry image only provides binaries compiled for x86_64 (linux/amd64) and lacks a multi-architecture manifest index.

Understanding the Root Causes

Modern container registries distribute multi-architecture images using an OCI Image Index (manifest list). When you run docker pull, the Docker daemon automatically detects your host CPU architecture and requests the corresponding platform layer. The failure happens when:

• Single-Architecture Upstream Repositories: Legacy or community images on Docker Hub were only built and tagged for linux/amd64.
• Outdated Image Tags: The requested tag (e.g., image:1.0) lacks multi-platform support, even if newer releases (e.g., image:latest) provide ARM64 images.
• Host Architecture Detection Mismatch: Docker Desktop or local virtualization environments querying linux/arm64/v8 while the image registry index strictly labels the platform as linux/amd64.
• Missing Multi-Platform Flags in Compose: Docker Compose attempting to pull an AMD64 service image without explicit emulation directives.

Step 1: Quick Fix – Force AMD64 Emulation via CLI Flag

Docker Desktop on macOS (via Rosetta 2) and Linux hosts (via QEMU and binfmt_misc) support running x86_64 containers seamlessly through emulation. Enforce the AMD64 architecture using the --platform flag:

# Force Docker CLI to pull and run the AMD64 variant under emulation
docker run --platform linux/amd64 -d -p 8080:80 my-legacy-image:latest

# Explicitly pull the AMD64 manifest entry
docker pull --platform linux/amd64 my-legacy-image:latest

# Verify the running container architecture
docker inspect -f '{{.Architecture}}' $(docker ps -lq)

Step 2: Update Docker Compose and Dockerfile Definitions

If the error occurs during docker compose up or inside a multi-stage Dockerfile build, declare the platform requirement explicitly in your configuration files:

# In docker-compose.yml, add the platform property to the affected service:
version: '3.8'
services:
  database:
    image: legacy-mysql:5.7
    platform: linux/amd64
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: secretpassword

For custom image builds that depend on an AMD64 base image, specify the platform in the FROM directive:

# In Dockerfile:
FROM --platform=linux/amd64 python:3.9-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

Step 3: Build Multi-Architecture Images Using Docker Buildx

If you maintain the repository, the permanent solution is compiling and publishing genuine multi-architecture images to Docker Hub or private registries using Buildx:

# Ensure Buildx is initialized with container driver
docker buildx create --name multiarch-builder --use
docker buildx inspect --bootstrap

# Build and push both ARM64 and AMD64 layers simultaneously
docker buildx build --platform linux/amd64,linux/arm64 -t username/my-app:latest --push .

# Inspect the published manifest list to verify platform availability
docker buildx imagetools inspect username/my-app:latest

Verification & Testing Steps

Inspect the local image manifest and verify that the container initializes and executes without architecture warnings:

# Inspect the architecture metadata of the downloaded image
docker image inspect my-legacy-image:latest --format '{{.Os}}/{{.Architecture}}'

# Expected output:
# linux/amd64

# Confirm container processes are running under emulation
docker exec -it $(docker ps -lq) uname -m
# Output will display: x86_64

Troubleshooting Summary Comparison

Resolution Method	Configuration Level	Trade-Offs & Performance
CLI --platform linux/amd64	Ad-hoc / Manual run	Fastest fix; minor CPU emulation overhead via Rosetta/QEMU
Compose platform: linux/amd64	Project / Team level	Ensures all Apple Silicon and ARM team members can run compose
Dockerfile FROM --platform=...	Build definition	Guarantees deterministic builds across developer machines and CI
docker buildx Multi-arch	Image Maintainer	Optimal; runs native ARM64 with maximum performance on M-series chips