ImagePullBackOff: images that cannot be pulled
ImagePullBackOff (and ErrImagePull before it) means the kubelet could not pull the container image. The pod never starts. The reason is almost always in the pod's events.
Find the reason with kubectl
kubectl describe pod <pod> -n <ns>and read the Events at the bottom. TheFailed to pull imagemessage names the cause.- Check the exact image reference:
kubectl get pod <pod> -n <ns> -o jsonpath="{.spec.containers[*].image}". - Try the pull from a machine with the same network access, for example
crictl pull <image>on the node.
Messages and what they mean
| Message contains | Cause | Fix |
|---|---|---|
manifest unknown, not found | The tag or digest does not exist | Fix the tag, or push the image. Check for typos and for tags deleted by a cleanup policy. |
unauthorized, authentication required, 403 | The registry needs credentials | Create a docker-registry Secret and reference it in imagePullSecrets (or on the ServiceAccount). |
i/o timeout, no such host, connection refused | The node cannot reach the registry | DNS, firewall, proxy settings of the container runtime, or a registry mirror for air-gapped clusters. |
x509: certificate signed by unknown authority | The registry uses a private CA | Add the CA to the container runtime's trusted certificates on every node. |
toomanyrequests | Registry rate limit (for example Docker Hub) | Authenticate, use a pull-through cache or mirror the image. |
no matching manifest for | No image for the node's architecture | Build a multi-arch image or schedule the pod on matching nodes. |
Prevent it
- Pin images by digest or by immutable tags in production.
- Keep pull secrets on the ServiceAccount so every pod in the namespace gets them.
- With GitOps, a bad tag in Git shows up as a Degraded Argo CD application: fix the tag in Git, not in the cluster.
The Kubby way
Kubby lists ImagePullBackOff pods at the top of Overview and Pods with the image and the registry's message on the row, so you see the cause without opening describe. In the Argo CD centre, "Why Degraded?" points at the pod that cannot pull its image.
