This error occurs when Docker cannot find an image variant built for your system's CPU architecture (linux/amd64). Common when pulling ARM-only images on Intel/AMD machines, or when using outdated tags. Fix by specifying the correct platform, finding multi-arch images, or building your own.
This error indicates that Docker's registry API returned a manifest list (also known as a fat manifest) that doesn't include a variant for the linux/amd64 architecture. A manifest list is an index pointing to multiple platform-specific image manifests, allowing registries to serve the correct image variant based on the client's architecture. When you pull an image, Docker sends your system's platform information (OS and architecture) to the registry. The registry looks up the manifest list for the requested image tag and tries to find a matching entry. If no entry exists for linux/amd64, this error is returned. This commonly happens when: - An image was built exclusively for ARM architecture (common with Raspberry Pi images) - The image maintainer hasn't published a linux/amd64 variant - You're using a tag that is temporarily unavailable or being rebuilt - The Docker Hub "latest" tag is being updated and momentarily missing architectures Unlike the related "platform mismatch" warning (which allows containers to run under emulation), this error completely blocks the image pull because Docker cannot find any variant to download.
First, verify what platforms the image actually supports:
# Using docker buildx imagetools (recommended)
docker buildx imagetools inspect IMAGE:TAG
# Alternative: Using manifest inspect
docker manifest inspect IMAGE:TAG
# Parse with jq to see just platforms
docker manifest inspect IMAGE:TAG | jq '.manifests[].platform'Example output for a multi-arch image:
{
"architecture": "amd64",
"os": "linux"
}
{
"architecture": "arm64",
"os": "linux"
}If linux/amd64 is missing from the list, you'll need to find an alternative image or build your own.
The issue may be specific to the tag you're using. Try these alternatives:
# Instead of 'latest', use a specific version
docker pull postgres:15 # instead of postgres:latest
# Check for architecture-specific tags
docker pull nginx:1.25-alpine-amd64 # if available
# Look for '-amd64' or '-x86_64' suffixed tags
docker pull some-image:v1.0-amd64Visit the image's Docker Hub page or registry to see all available tags. Many maintainers publish architecture-specific tags alongside multi-arch manifests.
If you were using 'latest' and it just started failing, wait a few minutes - the tag may be rebuilding on Docker Hub.
Search for alternative images that include amd64 support:
# Search Docker Hub for similar images
docker search IMAGE_NAME
# Check official images first - they usually support multiple architectures
docker buildx imagetools inspect nginx:latest
docker buildx imagetools inspect python:3.11Common alternatives:
- Official Docker images (docker.io/library/*)
- LinuxServer.io images (linuxserver/*)
- Bitnami images (bitnami/*)
These organizations typically maintain multi-architecture builds for their images.
If no suitable image exists, build your own from a multi-arch base:
# Dockerfile
FROM --platform=linux/amd64 alpine:latest
# Or use a multi-arch base and let Docker select
FROM alpine:latest
RUN apk add --no-cache your-packages
COPY . /app
CMD ["./app"]Build and push:
# Create a builder for multi-platform builds
docker buildx create --name mybuilder --use --bootstrap
# Build for multiple architectures
docker buildx build \
--platform linux/amd64,linux/arm64 \
--tag your-registry/your-image:latest \
--push \
.This creates a manifest list in your registry that includes both architectures.
A known issue with Docker Desktop 4.20+ can cause manifest resolution problems when the containerd image store is enabled:
1. Open Docker Desktop
2. Go to Settings (gear icon)
3. Select General
4. Uncheck "Use containerd for pulling and storing images"
5. Click Apply & restart
# After restart, verify the setting
docker info | grep "Storage Driver"
# Should show: overlay2 (not containerd)
# Try pulling the image again
docker pull IMAGE:TAGThis reverts to the classic image store which has more mature manifest handling. Re-enable containerd after Docker releases a fix.
Stale manifest data can sometimes cause this error. Clear the cache and retry:
# Remove all unused images, containers, networks, and cache
docker system prune -a
# Clear the buildx cache specifically
docker buildx prune -a
# Pull with explicit no-cache flag
docker pull --no-cache IMAGE:TAG
# Alternative: Remove specific image and repull
docker rmi IMAGE:TAG
docker pull IMAGE:TAGThis forces Docker to fetch fresh manifest data from the registry.
If you're building and pushing images in GitHub Actions, attestation can cause manifest list problems:
# .github/workflows/docker.yml
- name: Build and push
uses: docker/build-push-action@v5
with:
platforms: linux/amd64,linux/arm64
push: true
tags: user/app:latest
# Disable attestation to fix manifest issues
provenance: false
sbom: falseOr when using docker buildx directly:
docker buildx build \
--platform linux/amd64,linux/arm64 \
--provenance=false \
--sbom=false \
--push \
-t your-image:tag .Attestation adds extra manifests that some registries or Docker versions don't handle correctly.
If you must use an ARM-only image on amd64, you can try emulation (with significant performance penalty):
# Install QEMU handlers for cross-architecture execution
docker run --privileged --rm tonistiigi/binfmt --install all
# Try pulling with explicit ARM platform
docker pull --platform linux/arm64 IMAGE:TAG
# Run the ARM image under emulation
docker run --platform linux/arm64 IMAGE:TAGWarning: This runs ARM binaries through QEMU emulation on your x86 host, which is:
- 2-5x slower for CPU-bound tasks
- May have compatibility issues with some binaries
- Not recommended for production use
Consider building a native amd64 version of the image instead.
### Understanding Docker Manifest Lists
Docker uses manifest lists (also called "fat manifests" or "multi-arch manifests") to support multiple architectures from a single image reference. The structure looks like:
image:tag
└── manifest list (application/vnd.docker.distribution.manifest.list.v2+json)
├── linux/amd64 manifest → layers for x86_64
├── linux/arm64 manifest → layers for ARM 64-bit
└── linux/arm/v7 manifest → layers for ARM 32-bitWhen Docker pulls an image, it:
1. Fetches the manifest list from the registry
2. Filters for entries matching the client's platform
3. Downloads the matching manifest and its layers
The "no matching manifest" error occurs at step 2 when no entry matches.
### Registry-Specific Behavior
Different registries handle manifest lists differently:
| Registry | Behavior |
|----------|----------|
| Docker Hub | Full multi-arch support, may have rate limits |
| GitHub Container Registry (ghcr.io) | Full support, attestation can cause issues |
| Amazon ECR | Full support |
| Google Container Registry | Full support |
| Self-hosted registries | Varies by configuration |
### Debugging Manifest Issues
Use these commands to diagnose manifest problems:
# Get raw manifest from registry (requires authentication for private images)
curl -s -H "Accept: application/vnd.docker.distribution.manifest.list.v2+json" \
"https://registry-1.docker.io/v2/library/nginx/manifests/latest" | jq
# Check what Docker thinks your platform is
docker info --format '{{.OSType}}/{{.Architecture}}'
# Inspect local image platform
docker image inspect IMAGE:TAG --format '{{.Os}}/{{.Architecture}}'
# Enable Docker CLI debugging
DOCKER_CLI_EXPERIMENTAL=enabled docker manifest inspect IMAGE:TAG### Common Multi-Arch Base Images
These official base images reliably support linux/amd64:
- alpine - Minimal Linux (~5MB)
- debian / ubuntu - Full Linux distributions
- python / node / golang - Language-specific bases
- nginx / postgres / redis - Popular services
Always prefer official images when possible as they maintain multi-architecture builds.
### Docker BuildKit and Manifest Lists
When building multi-platform images locally, note that:
# This only keeps ONE architecture locally (last built or native)
docker buildx build --platform linux/amd64,linux/arm64 --load .
# To get a proper manifest list, you must push to a registry
docker buildx build --platform linux/amd64,linux/arm64 --push -t registry/image:tag .
# Or use the containerd image store (Docker Desktop)
docker buildx build --platform linux/amd64,linux/arm64 --load .The --load flag with multiple platforms only works with containerd image store enabled.
image 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