Kubernetes pod stuck in ErrImagePull or ImagePullBackOff
ErrImagePullShort answer
The kubelet could not pull the container image. Run kubectl describe pod and read the Events: they give the registry's reason. The common causes are a wrong image name or tag, a private registry with no imagePullSecrets, or a pull secret that lives in another namespace than the pod.
Fix it fast
1Find out which cause you have
Describe the pod and read the Events at the bottom. The registry's own message says whether the image is missing or access is denied.
kubectl describe pod <pod-name> -n <namespace>2Match what you see, then jump to its fix
- 1
Events show the image or tag cannot be foundThe image name or tag is wrong, or the image was never pushedFix - 2
Events show the registry refusing access, and docker pull works only after docker loginThe registry is private and the pod has no imagePullSecretsFix - 3
A secret is configured, yet the same pull error repeats in one namespace onlyThe pull secret exists, but in a different namespaceFix
- 1
What does the error look like?
ErrImagePullImagePullBackOff
Cause 1 of 3
The image name or tag is wrong, or the image was never pushed
1Check
Kubernetes lists a wrong image name, an image not pushed to the registry, and a manual pull test as the first things to check. Pull the exact string from the manifest by hand.
kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.containers[*].image}'
docker pull <image>2Fix
Correct the name or tag in the manifest, or push the missing image. Without a tag, Kubernetes assumes latest, so write the tag out.
containers:
- name: app
image: registry.example.com/team/app:1.4.23Verify
Apply the manifest and watch the pod become Running.
kubectl apply -f deployment.yaml
kubectl get pods -n <namespace> -wConfirmed by kubernetes.io
Cause 2 of 3
The registry is private and the pod has no imagePullSecrets
1Check
ImagePullBackOff covers pulling from a private registry without an imagePullSecret. Only pods that provide their own keys can use the private registry.
kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.imagePullSecrets}'2Fix
Create a docker-registry secret in the pod's namespace and reference it under imagePullSecrets.
kubectl create secret docker-registry regcred -n <namespace> \
--docker-server=<registry-server> \
--docker-username=<user> \
--docker-password=<password>
# pod spec
spec:
imagePullSecrets:
- name: regcred3Verify
Restart the workload and check that the pod starts.
kubectl get pods -n <namespace>Confirmed by kubernetes.io
Cause 3 of 3
The pull secret exists, but in a different namespace
1Check
imagePullSecrets must be Secrets in the same namespace as the pod, and each namespace needs its own copy.
kubectl get secret regcred -n <namespace>2Fix
Create the secret in the pod's namespace, or add it to the namespace's ServiceAccount so new pods get it automatically.
kubectl create secret docker-registry regcred -n <namespace> \
--docker-server=<registry-server> \
--docker-username=<user> \
--docker-password=<password>3Verify
The secret is found in the namespace.
kubectl get secret regcred -n <namespace>Confirmed by kubernetes.io
How do I stop it coming back?
- Pin images to a version tag or digest instead of latest.
- Pull each image by hand with the same string before you deploy it.
- Create the pull secret in every namespace as part of the namespace setup.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Kubernetes cannot pull an image from a plain HTTP or self-signed registry
docker pull works on a laptop, the same image fails in the cluster
Kubernetes nodes pull images through their container runtime, usually containerd, not through your Docker daemon.
4 causes, each with a fixServers
Argo CD behind an nginx Ingress loops with too many redirects
307 Temporary Redirect on every request to the Argo CD host
The browser and Argo CD disagree about who handles TLS.
3 causes, each with a fixServers
A cert-manager Certificate stays at READY False with Let's Encrypt
Issuing certificate as Secret does not exist
A Certificate that stays not ready is waiting on a chain: Issuer, CertificateRequest, Order, Challenge.
3 causes, each with a fixServers
Kubernetes in Docker Desktop will not start or stays on starting
kubectl shows no contexts, or errors against the docker-desktop context
When the Docker Desktop cluster hangs on starting, the usual causes are too few resources, a broken cluster state, or the kubeadm provisioner failing.
4 causes, each with a fixServers
EKS managed node group ends in Create failed because nodes never joined
NodeCreationFailure
Nodes that do not register within 15 minutes cause NodeCreationFailure and a Create failed status.
4 causes, each with a fixServers
An Elasticsearch pod keeps restarting with Back-off restarting failed container
CrashLoopBackOff
Back-off restarting failed container only says the container keeps dying.
3 causes, each with a fix