How to fix Error response from daemon: no matching manifest for linux/arm64/v8 in the manifest list entries in Docker

What this error means

This error means Docker cannot find an image variant that matches your system's CPU architecture in the image's manifest list. Docker images are compiled for specific CPU architectures (like amd64/x86_64 or arm64/aarch64), and the manifest list acts as an index pointing to architecture-specific versions. When you pull an image, Docker checks the manifest list for a variant matching your host platform. If the image only contains linux/amd64 entries but you're on a linux/arm64 system (like Apple Silicon Mac or Raspberry Pi), Docker cannot proceed because there's no compatible binary to run. This became a widespread issue with the adoption of Apple Silicon Macs (M1/M2/M3/M4 chips) and ARM-based cloud instances. Many older images were built only for x86/amd64, and while Docker can emulate different architectures, it cannot pull an image if the manifest explicitly lacks your platform.

Typical symptoms

• Docker pull fails with 'no matching manifest for linux/arm64/v8 in the manifest list entries'
• Docker run immediately fails before container starts on Apple Silicon Macs
• Images that worked on Intel Macs fail on M1/M2/M3 Macs
• Docker Compose up fails during image pull phase on ARM devices
• CI/CD pipelines fail when running on ARM64-based runners
• Raspberry Pi or ARM servers cannot pull certain Docker Hub images
• Same Dockerfile works on x86 servers but fails on ARM infrastructure

Common causes

1. The image maintainer has not published an ARM64 variant (most common cause)
2. Running on Apple Silicon Mac (M1/M2/M3/M4) which uses ARM64 architecture
3. Using Raspberry Pi or other ARM-based single-board computers
4. Deploying to ARM-based cloud instances (AWS Graviton, Azure ARM VMs)
5. Image is outdated and predates widespread ARM64 support
6. Using a niche or unmaintained Docker image without multi-arch builds
7. Image tag points to an architecture-specific digest rather than manifest list
8. Private registry not configured to serve multi-platform manifests correctly

How to fix "Error response from daemon: no matching manifest for linux/arm64/v8 in the manifest list entries"

# Using Docker buildx imagetools (recommended)
docker buildx imagetools inspect nginx:latest

# Using docker manifest (older method)
docker manifest inspect nginx:latest

# Example output showing supported platforms:
# Name:      docker.io/library/nginx:latest
# MediaType: application/vnd.oci.image.index.v1+json
# Digest:    sha256:...
#
# Platforms:
#   linux/amd64
#   linux/arm/v5
#   linux/arm/v7
#   linux/arm64      <-- ARM64 support present
#   linux/386

# Pull an amd64 image on ARM host (Apple Silicon, Raspberry Pi)
docker pull --platform linux/amd64 mysql:5.7

# Run with explicit platform specification
docker run --platform linux/amd64 mysql:5.7

# For any platform mismatch, specify the available platform
docker run --platform linux/amd64 your-image:tag

# Set for current terminal session
export DOCKER_DEFAULT_PLATFORM=linux/amd64

# Make it permanent by adding to shell profile
# For zsh (default on macOS):
echo 'export DOCKER_DEFAULT_PLATFORM=linux/amd64' >> ~/.zshrc
source ~/.zshrc

# For bash:
echo 'export DOCKER_DEFAULT_PLATFORM=linux/amd64' >> ~/.bashrc
source ~/.bashrc

# Verify it's set
echo $DOCKER_DEFAULT_PLATFORM

# docker-compose.yml
version: '3.8'
services:
  database:
    image: mysql:5.7
    platform: linux/amd64  # Force amd64 with emulation on ARM hosts
    environment:
      MYSQL_ROOT_PASSWORD: secret
    ports:
      - "3306:3306"

  app:
    image: your-app:latest
    # No platform specified - uses native architecture
    depends_on:
      - database

# Check Docker Hub for official multi-arch images
# Many official images now support: linux/amd64, linux/arm64, linux/arm/v7

# Examples of well-maintained multi-arch images:
docker pull nginx:latest          # Supports amd64 + arm64
docker pull postgres:15           # Supports amd64 + arm64
docker pull redis:7               # Supports amd64 + arm64
docker pull node:20               # Supports amd64 + arm64

# For MySQL, use version 8+ for ARM64 support
docker pull mysql:8.0             # Has ARM64 support
# Instead of mysql:5.7 which is amd64-only

# MariaDB as MySQL alternative with ARM64 support
docker pull mariadb:11

# Option 1: Install via package manager (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install -y qemu-user-static binfmt-support

# Option 2: Use Docker's multiarch image (works on any Linux)
docker run --privileged --rm tonistiigi/binfmt --install all

# Verify QEMU is registered
ls /proc/sys/fs/binfmt_misc/qemu-*
# Should show: qemu-aarch64, qemu-arm, qemu-x86_64, etc.

# Test cross-architecture execution
docker run --platform linux/arm64 arm64v8/alpine uname -m
# Should output: aarch64 (even on x86 host)

# Create a builder with multi-platform support
docker buildx create --name mybuilder --use --bootstrap

# Build for multiple architectures and push to registry
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag your-registry/your-image:latest \
  --push \
  .

# Verify the multi-arch manifest was created
docker buildx imagetools inspect your-registry/your-image:latest

Advanced notes

name: Multi-Arch Build

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - 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/app:latest

Frequently asked questions

What does "Error response from daemon: no matching manifest for linux/arm64/v8 in" mean?

This error means Docker cannot find an image variant that matches your system's CPU architecture in the image's manifest list. Docker images are compiled for specific CPU architectures (like amd64/x86_64 or arm64/aarch64), and the manifest list acts as an index pointing to architecture-specific versions. When you pull an image, Docker checks the manifest list for a variant matching your host platform.

How do I fix "Error response from daemon: no matching manifest for linux/arm64/v8 in"?

This error occurs when pulling a Docker image that doesn't have a version compiled for your CPU architecture. Common on Apple Silicon Macs (M1/M2/M3) and ARM-based systems like Raspberry Pi when trying to use x86/amd64-only images. Fix by using the --platform flag, setting DOCKER_DEFAULT_PLATFORM, or finding multi-architecture images.

What causes "Error response from daemon: no matching manifest for linux/arm64/v8 in"?

The image maintainer has not published an ARM64 variant (most common cause) Running on Apple Silicon Mac (M1/M2/M3/M4) which uses ARM64 architecture Using Raspberry Pi or other ARM-based single-board computers

Is the "Error response from daemon: no matching manifest for linux/arm64/v8 in" error serious?

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

Related errors

• Error response from daemon: no matching manifest for linux/amd64 in the manifest list entries

  How to fix 'no matching manifest for linux/amd64' in Docker

  MEDIUM

• failed to solve: failed to compute cache key: failed to calculate checksum: no build stage in current context

  How to fix 'no build stage in current context' in Docker

  MEDIUM

• Error response from daemon: no matching manifest for linux/arm64 in the manifest list entries

  How to fix 'no matching manifest for linux/arm64' in Docker

  MEDIUM

• no basic auth credentials

  How to fix 'no basic auth credentials' in Docker

  LOW

• 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 Blog - Building Multi-Arch Images(Official Docs)
• 💬
  Stack Overflow - Docker Apple Silicon MySQL manifest error(Stack Overflow)
• 💬
  Docker Forums - Manifest list troubleshooting(Stack Overflow)
• 📝
  DevCoops - Apple M1 Docker manifest fix
• 📝
  100 Common Docker Errors & Solutions