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.
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.
First, identify your host platform:
docker info --format '{{.OSType}}/{{.Architecture}}'
# Output: linux/amd64 or linux/arm64Then check what architectures the image supports:
# 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'If the image has your architecture but Docker isn't selecting it correctly:
# 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 -mIn Docker Compose:
services:
web:
image: node:18-alpine
platform: linux/amd64Warning: Using --platform for a different architecture enables QEMU emulation, which is 2-10x slower.
Create images supporting both amd64 and arm64:
# 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:latestOptimize Dockerfile for cross-compilation:
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"]Most official images are multi-arch. Verify before using:
# 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-bookwormCheck any third-party image before use:
docker buildx imagetools inspect <image>:<tag>If you can't rebuild the image, constrain pods to matching nodes:
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:latestCheck node architectures:
kubectl get nodes -o wide
kubectl get node <NODE> -o jsonpath='{.status.nodeInfo.architecture}'Label nodes if not already labeled:
kubectl label node <NODE> kubernetes.io/arch=amd64GitHub Actions example:
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:latestQEMU enables building for architectures different from the runner.
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:
myapp:latest (Manifest List)
├── linux/amd64 → Manifest A
├── linux/arm64 → Manifest B
└── linux/arm/v7 → Manifest CIf 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.
No subnets found for EKS cluster
How to fix "eks subnet not found" in Kubernetes
unable to compute replica count
How to fix "unable to compute replica count" in Kubernetes HPA
error: context not found
How to fix "error: context not found" in Kubernetes
default backend - 404
How to fix "default backend - 404" in Kubernetes Ingress
serviceaccount cannot list resource
How to fix "serviceaccount cannot list resource" in Kubernetes