How to fix no matching manifest for linux/amd64 in Kubernetes

KubernetesINTERMEDIATEMEDIUMUpdated Dec 5, 2025· 215 views

This error occurs when the container image doesn't have a variant for your node's architecture. Fix it by building multi-architecture images with docker buildx or using the --platform flag to specify an available architecture.

Quick fix

Fixes no matching manifest for linux/amd64

docker info --format '{{.OSType}}/{{.Architecture}}'
# Output: linux/amd64 or linux/arm64
  1. Check your platform and image architectures
  2. Force pull for specific architecture
  3. Build multi-architecture images with buildx
  4. Use official multi-arch base images
kubernetes — error
docker info --format '{{.OSType}}/{{.Architecture}}'
# Output: linux/amd64 or linux/arm64
no matching manifest for linux/amd64

What this error means

The "no matching manifest for linux/amd64" error occurs when your Docker daemon or Kubernetes node requests an image for a specific platform (like linux/amd64), but the registry's manifest list doesn't include that architecture. Modern container images can be multi-architecture, containing variants for different platforms (amd64, arm64, etc.) in a single manifest list. When you pull an image, Docker automatically selects the variant matching your host. If your platform isn't available, you get this error. This commonly happens when pulling images built only for ARM (like some Raspberry Pi images) on an x86-64 server, or when Apple Silicon Macs try to pull amd64-only images. In mixed-architecture Kubernetes clusters, pods may fail on some nodes but succeed on others.

Typical symptoms

  • Docker pull fails with "no matching manifest for linux/amd64"
  • Kubernetes pods enter ImagePullBackOff on specific nodes
  • Works on some cluster nodes but fails on others
  • CI/CD builds succeed but deployment fails (different architectures)
  • Apple Silicon Mac cannot pull certain images
  • "exec format error" after successful pull (binary incompatibility)

Common causes

  1. Image only built for single architecture (arm64-only or amd64-only)
  2. Pulling ARM image on x86-64 node or vice versa
  3. Mixed-architecture Kubernetes cluster with single-arch images
  4. Docker Desktop on Apple Silicon defaulting to linux/arm64
  5. CI/CD runner architecture differs from deployment target

How to fix "no matching manifest for linux/amd64"

1Check your platform and image architectures

First, identify your host platform:

bash
docker info --format '{{.OSType}}/{{.Architecture}}'
# Output: linux/amd64 or linux/arm64

Then check what architectures the image supports:

bash
# Using docker buildx
docker buildx imagetools inspect docker.io/library/python:latest

# Using docker manifest
docker manifest inspect -v ubuntu:latest | grep -i platform

# Check specific architectures
docker manifest inspect --verbose nginx:latest | jq '.[].Descriptor.platform'
2Force pull for specific architecture

If the image has your architecture but Docker isn't selecting it correctly:

bash
# Explicitly specify platform
docker pull --platform=linux/amd64 ubuntu:latest
docker pull --platform=linux/arm64 node:18-alpine

# Run with explicit platform (uses QEMU emulation if mismatched)
docker run --rm --platform=linux/amd64 ubuntu:latest uname -m

In Docker Compose:

yaml
services:
  web:
    image: node:18-alpine
    platform: linux/amd64

Warning: Using --platform for a different architecture enables QEMU emulation, which is 2-10x slower.

3Build multi-architecture images with buildx

Create images supporting both amd64 and arm64:

bash
# Create buildx builder
docker buildx create --use --name multi-arch-builder
docker buildx inspect --bootstrap

# Build and push multi-arch image
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --push \
  -t myregistry/myapp:latest \
  .

# Verify the manifest list
docker buildx imagetools inspect myregistry/myapp:latest

Optimize Dockerfile for cross-compilation:

dockerfile
FROM --platform=$BUILDPLATFORM golang:1.21 AS builder
ARG TARGETOS TARGETARCH
WORKDIR /app
COPY . .
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o app main.go

FROM --platform=$TARGETPLATFORM alpine:latest
COPY --from=builder /app/app /app
CMD ["/app"]
4Use official multi-arch base images

Most official images are multi-arch. Verify before using:

dockerfile
# These are multi-arch safe
FROM alpine:3.18
FROM ubuntu:22.04
FROM debian:bookworm
FROM node:18-alpine
FROM python:3.11
FROM golang:1.21

# Pin to specific multi-arch version
FROM python:3.11.7-slim-bookworm

Check any third-party image before use:

bash
docker buildx imagetools inspect <image>:<tag>
5Use nodeSelector for single-arch images in Kubernetes

If you can't rebuild the image, constrain pods to matching nodes:

yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  template:
    spec:
      nodeSelector:
        kubernetes.io/arch: amd64  # Only schedule on amd64 nodes
      containers:
      - name: app
        image: amd64-only-image:latest

Check node architectures:

bash
kubectl get nodes -o wide
kubectl get node <NODE> -o jsonpath='{.status.nodeInfo.architecture}'

Label nodes if not already labeled:

bash
kubectl label node <NODE> kubernetes.io/arch=amd64
6Configure CI/CD for multi-arch builds

GitHub Actions example:

yaml
name: Build Multi-Arch Image
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:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: myregistry/myapp:latest

QEMU enables building for architectures different from the runner.

Advanced notes

ARM vs x86 Considerations:
- ARM64 (arm64/v8): Growing adoption (AWS Graviton, Apple Silicon), lower power, often 20-30% cheaper
- x86-64 (amd64): Standard server platform, broader software compatibility
- Mixed clusters: Kubernetes auto-selects correct variant if multi-arch manifest exists

Apple Silicon (M1/M2/M3):
- Docker Desktop defaults to linux/arm64
- --platform=linux/amd64 enables QEMU emulation (2-3x slower)
- Best solution: Build and push multi-arch images

Manifest List Structure:

bash
myapp:latest (Manifest List)
├── linux/amd64 → Manifest A
├── linux/arm64 → Manifest B
└── linux/arm/v7 → Manifest C

If your platform isn't listed, you get "no matching manifest".

QEMU Emulation vs Native: Native builds are fastest. Building amd64 on arm64 (or vice versa) uses QEMU with 2-10x overhead. Use multi-stage builds with BUILDPLATFORM/TARGETPLATFORM to compile natively when possible.

Related Error: "exec format error" is the same root cause but caught at runtime instead of pull time.

Frequently asked questions

What does "no matching manifest for linux/amd64" mean?
The "no matching manifest for linux/amd64" error occurs when your Docker daemon or Kubernetes node requests an image for a specific platform (like linux/amd64), but the registry's manifest list doesn't include that architecture. ) in a single manifest list. When you pull an image, Docker automatically selects the variant matching your host.
How do I fix "no matching manifest for linux/amd64"?
This error occurs when the container image doesn't have a variant for your node's architecture. Fix it by building multi-architecture images with docker buildx or using the --platform flag to specify an available architecture.
What causes "no matching manifest for linux/amd64"?
Image only built for single architecture (arm64-only or amd64-only) Pulling ARM image on x86-64 node or vice versa Mixed-architecture Kubernetes cluster with single-arch images
Is the "no matching manifest for linux/amd64" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading