How to Fix Kubernetes ImagePullBackOff
Quick Fix Summary
TL;DRCheck pod events for the specific error, then verify image name, tag, and registry credentials.
ImagePullBackOff indicates Kubernetes cannot retrieve the specified container image for a Pod. It's a critical failure that prevents application deployment or scaling.
Diagnosis & Causes
Recovery Steps
Step 1: Diagnose with kubectl describe
Get the exact error message from the Pod's events to understand the root cause.
kubectl describe pod <pod-name> -n <namespace>
# Look for the 'Events:' section at the bottom of the output.Step 2: Verify Image Name and Pull Manually
Ensure the image reference is correct and test pulling it directly with Docker or Podman.
# 2a. Check the image in your deployment/pod manifest.
kubectl get deployment <deployment-name> -o yaml | grep image
# 2b. Attempt to pull the image locally to verify it exists.
docker pull <full-image-name:tag>Step 3: Configure Secrets for Private Registries
If using a private registry (e.g., ECR, GCR, private Docker Hub), create an imagePullSecret.
# Create a Docker registry secret.
kubectl create secret docker-registry regcred \
--docker-server=<your-registry-server> \
--docker-username=<your-username> \
--docker-password=<your-password> \
--docker-email=<your-email>
# Patch the default service account to use the secret (or add to Pod spec).
kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "regcred"}]}'Step 4: Emergency Rollback & Use a Public Image
For immediate recovery, rollback to a previous working version or use a known-public image as a stopgap.
# Rollback a deployment to the previous revision.
kubectl rollout undo deployment/<deployment-name>
# OR, as a last resort, patch the deployment with a public 'busybox' image to get running.
kubectl set image deployment/<deployment-name> <container-name>=busybox:latestArchitect's Pro Tip
"For AWS ECR, use an IAM role for the node or kubelet, not static credentials. For 'manifest unknown' errors, the tag likely doesn't exist."
Frequently Asked Questions
What's the difference between ImagePullBackOff and ErrImagePull?
ErrImagePull is the initial error. ImagePullBackOff is the state where Kubernetes is waiting before retrying the failed pull, creating a backoff cycle.
How do I fix 'pull access denied' for a public image?
This often indicates a rate limit (e.g., Docker Hub). Authenticate with a paid account or use the imagePullSecrets workaround with a valid token.