ImagePullBackOff
The kubelet tried to pull the image, failed (ErrImagePull), and is now waiting longer between attempts (ImagePullBackOff). The reason is always in the pod’s events.
Diagnose in order
Section titled “Diagnose in order”- Read the exact pull error:
kubectl describe pod <pod> | sed -n '/Events:/,$p'. TheFailedevent quotes the registry’s answer. - Check the image reference character by character:
kubectl get pod <pod> -o jsonpath='{.spec.containers[*].image}'. - For private registries, check the pull secret is referenced and in the same namespace:
kubectl get pod <pod> -o jsonpath='{.spec.imagePullSecrets}', thenkubectl get secret <name> -n <ns>. - From the node, if you have access:
crictl pull <image>reproduces the pull with the runtime’s own credentials and network.
Usual causes
Section titled “Usual causes”| Event message contains | Cause |
|---|---|
not found, manifest unknown |
The tag or digest doesn’t exist (typo, tag never pushed, or deleted) |
unauthorized, authentication required, denied |
No pull secret, wrong secret, or expired registry credentials |
no such host, i/o timeout, connection refused |
The node can’t reach the registry: DNS, proxy, firewall, or air-gapped node without a mirror |
toomanyrequests |
Registry rate limiting, common with anonymous pulls from Docker Hub |
no matching manifest for linux/arm64 |
The image wasn’t built for the node’s CPU architecture |
Correct the reference or push the missing tag; create the pull secret in the pod’s namespace and reference it (or attach it to the service account); or fix the node’s network path to the registry. In regulated environments, pull only from an internal mirror and block public registries, which turns rate limits and supply-chain surprises into a non-issue.
Read next: Deployments and rollouts, where a bad tag stalls a rollout.