This error occurs when Docker finds an image in the registry but it doesn't have a variant for your requested platform (architecture). This commonly happens when pulling images on ARM-based systems (Apple Silicon, Raspberry Pi) where the image only supports x86/amd64. The fix involves using multi-architecture images, building for the correct platform, or enabling emulation.
This error indicates that Docker successfully located the image you requested in the container registry, but the image's manifest doesn't include a variant compatible with the platform you specified or your host's native architecture. Docker images are built for specific CPU architectures (like amd64, arm64, arm/v7). When you pull an image, Docker checks the manifest list (also called a "fat manifest" for multi-arch images) to find a variant matching your platform. If no match exists, you get this error. This is different from a simple "image not found" error - the image exists, but not for your architecture. This commonly occurs in these scenarios: - Running on Apple Silicon (M1/M2/M3/M4) Macs where many older images only support amd64 - Using Raspberry Pi or other ARM devices with images built only for x86 - Explicitly requesting a platform with `--platform` that the image doesn't support - CI/CD environments using ARM runners with legacy amd64-only images
First, inspect what platforms the image actually supports:
# Using Docker buildx to inspect manifest
docker buildx imagetools inspect nginx:latest
# Example output shows supported platforms:
# Name: docker.io/library/nginx:latest
# MediaType: application/vnd.docker.distribution.manifest.list.v2+json
# Digest: sha256:abc123...
#
# Manifests:
# Name: docker.io/library/nginx:latest@sha256:...
# Platform: linux/amd64
# Name: docker.io/library/nginx:latest@sha256:...
# Platform: linux/arm64
# Platform: linux/arm/v7
# Using manifest inspect (requires experimental features)
docker manifest inspect mysql:5.7If your platform isn't listed, the image doesn't natively support your architecture. You'll need to use an alternative image, build your own, or use emulation.
Search for alternative images that support your platform:
# Check your system's architecture
docker info --format '{{.OSType}}/{{.Architecture}}'
# Example: linux/arm64
# Search for arm64-specific image variants
# Many images have architecture-specific tags or repos:
# - arm64v8/nginx instead of nginx
# - mysql:8.0-arm64 instead of mysql:8.0
# - library/alpine (multi-arch) vs alpine/armhf
# Official images on Docker Hub usually support multiple architectures
# Check the "Tags" tab on Docker Hub for architecture-specific tagsFor popular software, check if the official image supports your architecture. Most major images (nginx, postgres, node, python) now support both amd64 and arm64.
If you must use an image that doesn't support your architecture, enable emulation:
On Docker Desktop (Mac/Windows):
1. Open Docker Desktop Settings
2. Go to General tab
3. Enable "Use Rosetta for x86_64/amd64 emulation on Apple Silicon" (Mac only)
4. Click Apply & restart
# Now you can pull and run amd64 images on ARM:
docker pull --platform linux/amd64 your-image:tag
docker run --platform linux/amd64 your-image:tag
# The image runs under emulation (slower but functional)On Linux servers:
# Install QEMU for cross-architecture emulation
docker run --privileged --rm tonistiigi/binfmt --install all
# Verify emulation is available
cat /proc/sys/fs/binfmt_misc/qemu-x86_64
# Now pull and run with platform specification
docker run --platform linux/amd64 your-image:tagNote: Emulated containers run 2-5x slower than native. Use this for development/testing, not production.
If you control the Dockerfile, build a multi-architecture image:
# Create a new builder for multi-platform builds
docker buildx create --name multibuilder --use --bootstrap
# Build for multiple platforms 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:latestYour Dockerfile may need adjustments for cross-platform compatibility:
# Use a multi-arch base image
FROM --platform=$TARGETPLATFORM node:20-alpine
# Architecture-aware package installation
ARG TARGETARCH
RUN if [ "$TARGETARCH" = "arm64" ]; then \
echo "Installing ARM64 packages"; \
else \
echo "Installing AMD64 packages"; \
fiWhen using Docker Compose, specify the platform per service:
# docker-compose.yml
version: '3.8'
services:
legacy-app:
image: old-image:latest
platform: linux/amd64 # Force amd64 with emulation
ports:
- "8080:8080"
modern-app:
image: new-image:latest
# No platform specified - uses native architecture
ports:
- "3000:3000"# Run with explicit platform override
DOCKER_DEFAULT_PLATFORM=linux/amd64 docker-compose upThis ensures legacy services that only support amd64 can run alongside native services.
Sometimes stale cache causes manifest mismatches. Clear it and retry:
# Remove cached image data
docker image rm your-image:tag
# Clear buildx cache
docker buildx prune -f
# Pull fresh with explicit platform
docker pull --platform linux/arm64 your-image:tag
# If using a private registry, the registry itself may cache old manifests
# Contact your registry admin or wait for cache expirationFor Docker Hub, manifest caching typically refreshes within minutes. Private registries may have longer cache TTLs.
For abandoned images without multi-arch support, create your own:
# Clone the original Dockerfile (usually on GitHub)
git clone https://github.com/original/image-repo
cd image-repo
# Create multi-platform builder
docker buildx create --name mybuilder --use
# Build for your needed platforms
docker buildx build \
--platform linux/amd64,linux/arm64 \
--tag your-dockerhub/forked-image:latest \
--push \
.Then update your configurations to use your forked image:
# docker-compose.yml
services:
app:
# image: abandoned/old-image:latest # Old single-arch
image: your-dockerhub/forked-image:latest # Your multi-arch forkConsider contributing your multi-arch build back to the original project via pull request.
### Understanding Docker Manifests and Platform Selection
Docker uses manifest lists (OCI image index) to support multiple architectures. When you docker pull nginx:latest:
1. Docker requests the manifest list from the registry
2. The registry returns a list of platform-specific manifests
3. Docker selects the manifest matching your platform
4. Docker pulls the layers for that specific manifest
# View raw manifest data
docker manifest inspect --verbose nginx:latest | jq '.manifests[] | {platform: .platform, digest: .digest}'### CI/CD Multi-Architecture Build Patterns
GitHub Actions example:
name: Multi-Arch Build
on: push
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: Build and push
uses: docker/build-push-action@v5
with:
platforms: linux/amd64,linux/arm64,linux/arm/v7
push: true
tags: user/app:latest### Platform-Specific Base Image Selection
Some base images require platform-aware selection:
# Use ARG to make platform available
ARG TARGETPLATFORM
ARG BUILDPLATFORM
# Log what we're building
RUN echo "Building on $BUILDPLATFORM for $TARGETPLATFORM"
# Platform-conditional logic
FROM --platform=$TARGETPLATFORM alpine:latest AS runtime
RUN apk add --no-cache ca-certificates
# For binaries that differ by architecture
COPY --from=builder /app/bin-$TARGETARCH /app/bin### Common Architecture Naming
| Docker Platform | CPU Architecture | Common Devices |
|-----------------|------------------|----------------|
| linux/amd64 | x86_64 | Intel/AMD PCs, most cloud VMs |
| linux/arm64 | aarch64 | Apple Silicon, AWS Graviton, Raspberry Pi 4+ (64-bit) |
| linux/arm/v7 | armhf | Raspberry Pi 2/3 (32-bit), older ARM devices |
| linux/arm/v6 | armel | Raspberry Pi 1, Pi Zero |
| linux/386 | x86 (32-bit) | Legacy 32-bit systems |
### Registry-Specific Considerations
Docker Hub: Full multi-manifest support. Most official images support amd64 + arm64.
Amazon ECR: Supports manifest lists. Use aws ecr batch-get-image to verify platforms.
Google GCR/Artifact Registry: Full support. Use gcloud artifacts docker images describe to check.
Self-hosted registries: Ensure you're running Registry v2.3+ with manifest list support enabled.
### Debugging Manifest Issues
# Check what Docker thinks your platform is
docker version --format '{{.Server.Os}}/{{.Server.Arch}}'
# See detailed platform info
docker info | grep -E "(Architecture|OS)"
# Test platform availability without pulling
docker manifest inspect --verbose redis:7 2>&1 | grep -A2 "platform"
# Force refresh manifest from registry (bypass local cache)
docker pull --disable-content-trust your-image:tagimage operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub