How to Fix Kubernetes ErrImagePull / ImagePullBackOff
Quick Fix Summary
TL;DRCheck pod events for auth errors, verify image name/tag, and ensure registry credentials are configured in your secret.
ImagePullBackOff occurs when Kubernetes cannot pull a container image for a pod. This prevents pod startup and halts application deployment.
Diagnosis & Causes
Recovery Steps
Step 1: Diagnose with kubectl describe
Get detailed error messages from the pod events to identify the specific failure.
kubectl describe pod <pod-name> -n <namespace>
kubectl get events --sort-by='.lastTimestamp' -n <namespace>Step 2: Verify image name and tag
Ensure the image reference in your deployment is correct and accessible.
kubectl get deployment <deployment-name> -o=jsonpath='{.spec.template.spec.containers[*].image}'
docker pull <image-name:tag>Step 3: Check and configure imagePullSecrets
Create or verify Docker registry secrets for private repositories.
kubectl create secret docker-registry regcred \
--docker-server=<your-registry-server> \
--docker-username=<your-name> \
--docker-password=<your-password> \
--docker-email=<your-email> -n <namespace>
kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "regcred"}]}' -n <namespace>Step 4: Test network connectivity to registry
Verify that your cluster nodes can reach the container registry.
kubectl run -it --rm debug --image=busybox --restart=Never -- sh
nslookup registry-1.docker.io
wget -O- https://registry-1.docker.io/v2/Step 5: Check node disk space and Docker daemon
Inspect worker node resources and Docker/container runtime status.
kubectl get nodes -o wide
kubectl describe node <node-name> | grep -A 10 -B 5 "DiskPressure"
ssh <node-ip> "df -h /var/lib/docker; systemctl status docker"Step 6: Use imagePullPolicy: Always for development
Force Kubernetes to always pull the latest image during debugging.
apiVersion: apps/v1
kind: Deployment
spec:
template:
spec:
containers:
- name: app
image: myapp:latest
imagePullPolicy: AlwaysArchitect's Pro Tip
"For AWS ECR, use 'aws ecr get-login-password' to generate temporary tokens instead of static credentials in your imagePullSecrets."
Frequently Asked Questions
What's the difference between ErrImagePull and ImagePullBackOff?
ErrImagePull is the initial failure state. After repeated retries, Kubernetes enters the ImagePullBackOff state with exponential backoff between attempts.
How do I fix 'unauthorized: authentication required' errors?
Create a docker-registry secret with correct credentials and reference it in your pod spec or service account.
Can I use a local image to avoid pull errors?
Yes, set imagePullPolicy: Never and ensure the image exists on all nodes, but this isn't recommended for production.