Fix: Kubernetes ImagePullBackOff

!Symptoms

• Pod status shows ImagePullBackOff or ErrImagePull
• Pod is stuck in Pending state
• kubectl describe pod shows 'Failed to pull image' events

?Root Causes

• Image tag does not exist in the registry
• Private registry credentials (imagePullSecret) are missing or wrong
• Registry is unreachable due to network policy or firewall
• Docker Hub rate limiting (429 Too Many Requests)
• Typo in the image name or tag

#Diagnosis Steps

1. 1Run `kubectl describe pod <pod-name>` and read the Events section
2. 2Verify the exact image name and tag exist: `docker pull <image>` from your machine
3. 3Check imagePullSecrets: `kubectl get pod <pod-name> -o jsonpath='{.spec.imagePullSecrets}'`
4. 4Test registry auth: `kubectl get secret <secret-name> -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d`
5. 5Check node network: can the node reach the registry?

>Fix

1. 1Correct the image name or tag in your deployment manifest
2. 2Create or update the imagePullSecret: `kubectl create secret docker-registry`
3. 3Add imagePullSecrets to the pod spec or the default service account
4. 4If Docker Hub rate limited, use a pull-through cache or authenticate
5. 5Push the missing image to the registry if it was never built

*Prevention

• Use image digest pinning instead of mutable tags like 'latest'
• Set up a private registry mirror to avoid rate limits
• Automate imagePullSecret creation with tools like External Secrets Operator
• Include image existence checks in CI/CD pipelines before deploying
• Use always-pull policy for production, if-not-present for dev

Related Error Messages