Skip to content

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.

  1. Read the exact pull error: kubectl describe pod <pod> | sed -n '/Events:/,$p'. The Failed event quotes the registry’s answer.
  2. Check the image reference character by character: kubectl get pod <pod> -o jsonpath='{.spec.containers[*].image}'.
  3. For private registries, check the pull secret is referenced and in the same namespace: kubectl get pod <pod> -o jsonpath='{.spec.imagePullSecrets}', then kubectl get secret <name> -n <ns>.
  4. From the node, if you have access: crictl pull <image> reproduces the pull with the runtime’s own credentials and network.
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.