☸️
Kubernetes Error
Kubernetes Error: ImagePullBackOff
Kubernetes cannot pull the container image specified in the pod spec — usually a wrong image name/tag, or missing registry credentials.
What This Error Means
ImagePullBackOff means the kubelet tried to pull the container image for this pod and failed, and is now backing off (waiting progressively longer) before retrying — the pod never even gets to start a container because the image itself can't be retrieved.
Why It Occurs
Most commonly the image name or tag is misspelled or doesn't exist, the image is in a private registry and the cluster lacks the credentials (imagePullSecrets) to authenticate, or there's a network connectivity issue between the node and the registry.
Symptoms
- ⚠ `kubectl get pods` shows ImagePullBackOff or the earlier transient state ErrImagePull
- ⚠ Pod never starts any container
Common Causes
- • Typo in the image name or tag in the pod/deployment spec
- • Image genuinely doesn't exist at that tag (e.g. referencing a tag that was never pushed)
- • Private registry requires authentication and no imagePullSecret is configured
- • Node cannot reach the registry due to network/firewall/DNS issues
How to Fix It
- Check the exact error via `kubectl describe pod pod-name` — the Events section shows the precise pull failure reason (not found vs. unauthorized vs. network error)
- Verify the image name and tag are exactly correct by trying to pull it manually: `docker pull the-exact-image:tag`
- If the image is in a private registry, confirm an imagePullSecret is created and referenced in the pod spec's `imagePullSecrets` field
- If it's a network issue, confirm the node can reach the registry (DNS resolution, firewall rules) — test from the node itself if possible
- If using a CI/CD pipeline, confirm the image was actually pushed successfully to the registry before the deployment tries to pull it
| Command | Purpose |
|---|---|
| kubectl describe pod pod-name | See the exact image pull error in the Events section |
| docker pull the-exact-image:tag | Manually test whether the image can be pulled at all |
Advertisement
Verification
- ✓ `kubectl get pods` shows the pod progressing past ImagePullBackOff into ContainerCreating and then Running
Prevention
- → Use CI/CD pipeline steps that verify an image push succeeded before triggering a deployment referencing it
- → Use specific image tags (not `:latest`) so a typo or missing tag is caught predictably
- → Store registry credentials as Kubernetes Secrets and reference them consistently across deployments