How to fix ImagePullBackOff in Kubernetes

1. Read the event message

At the end of describe, the Failed event carries the exact error the registry returned:

kubectl describe pod <pod> -n <namespace>

What the message means

• not found or manifest unknown: the image or tag does not exist in that registry. Check for typos, a deleted tag or an image pushed to another repository.
• unauthorized, authentication required, 401 or 403: the registry is private and the pod has no valid credential.
• toomanyrequests: Docker Hub rate-limited pulls from the nodes’ egress IP.
• i/o timeout, no such host or dial tcp: the node cannot reach the registry (DNS, firewall, proxy or a private cluster without an egress route).
• no matching manifest for linux/arm64 (or amd64): the image was not published for the node’s architecture.

2. Check the image the pod asks for

kubectl get pod <pod> -n <namespace> \
  -o jsonpath='{.spec.containers[*].image}'

3. Private registry: imagePullSecret

Create a docker-registry Secret in the pod’s namespace and reference it in spec.imagePullSecrets, or in the ServiceAccount the pod uses:

kubectl create secret docker-registry regcred -n <namespace> \
  --docker-server=<registry> --docker-username=<user> --docker-password=<password>
kubectl patch serviceaccount default -n <namespace> \
  -p '{"imagePullSecrets":[{"name":"regcred"}]}'

AKS with ACR and EKS with ECR

• On AKS, attach the registry to the cluster with az aks update --attach-acr <acr>, which gives the kubelet pull permission without a Secret.
• On EKS, the nodes’ IAM role needs ECR read access (the AmazonEC2ContainerRegistryReadOnly policy), and the repository must be in the same account or allow the cluster’s account.

4. After the fix

The kubelet retries on its own, but the wait between attempts reaches 5 minutes. To skip the wait, restart the deployment:

kubectl rollout restart deployment/<name> -n <namespace>

Without a terminal, in Kubepier

In Kubepier, a pod in ImagePullBackOff shows up among the failing pods and the event with the registry’s message rises to the top of the warnings, from any cluster, in the browser or on your phone. On Pro, restarting the deployment is one click.