If you are seeing ImagePullBackOff in your Kubernetes cluster, here is how to fix it.
What This Error Means
ImagePullBackOff means Kubernetes cannot pull the container image. It tried and failed, and is now backing off before retrying.
Common causes:
- Image name or tag is wrong
- Image does not exist in the registry
- Authentication credentials are missing or expired
- Registry is down or unreachable
- Network policy blocking registry access
How to Diagnose
# Check pod status
kubectl get pods -o wide
# Describe the affected pod
kubectl describe pod <pod-name>
# Check events
kubectl get events --sort-by='.lastTimestamp' -AIdentify the Exact Error
kubectl describe pod <pod-name> | grep -A10 'Events'
# Look for: 'Failed to pull image' with the specific reasonCommon Fixes
1. Wrong Image Name
# Check what image the pod is trying to pull
kubectl get pod <pod-name> -o jsonpath='{.spec.containers[0].image}'
# Verify image exists
docker pull <image-name> # or: crane manifest <image-name>2. Missing Registry Credentials
# Create registry secret
kubectl create secret docker-registry regcred \
--docker-server=registry.example.com \
--docker-username=user \
--docker-password=pass
# Patch service account
kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "regcred"}]}'3. Private Registry with Expired Token
# Check secret expiry
kubectl get secret regcred -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d
# Delete and recreate with fresh credentials
kubectl delete secret regcred
kubectl create secret docker-registry regcred --docker-server=... --docker-username=... --docker-password=...Verify the Fix
# Force a new pull attempt
kubectl delete pod <pod-name>
# Deployment will create a new pod that pulls the imagePrevention
- Set proper resource requests and limits
- Use pod disruption budgets for critical workloads
- Monitor cluster health with Prometheus and Grafana
- Implement proper health checks (readiness and liveness probes)
