ImagePullBackOff
This error occurs when Kubernetes cannot pull a container image from a registry, resulting in a back-off state.
Usually happens because:
- ☑ Image name string typos or missing version tag on registry servers
- ☑ Missing imagePullSecrets mapping credentials for private repositories
- ☑ Exceeded anonymous pull limits on public libraries (Docker Hub limits)
🔍 Quick Checklist:
What is ImagePullBackOff?
An 'ImagePullBackOff' is a container lifecycle status indicating that Kubernetes attempted to pull a container image from a registry but failed. Rather than looping continuously, the Kubelet enters a back-off scheduling phase, doubling the retry delay up to 5 minutes. This is a follow-up status to 'ErrImagePull'. Common reasons include typo errors in the image name or tag, attempting to access private registries without imagePullSecrets, or exceeding registry download limits (like Docker Hub rate limits). In Kubernetes v1.36 environments, Container Runtime Interface (CRI) endpoints communicate these failures with rich status codes.
Common Causes
- Spelling typo in image tag or name: Mismatch in image name string or version tag (e.g. referencing 'nginx:latst' instead of 'nginx:latest').
- Missing registry credentials: Running Pods referencing private registries (e.g. AWS ECR, GCP GAR, or Docker Hub private repos) without configuring 'imagePullSecrets' in the Pod specification.
- Registry rate limiting: Exceeding anonymous pull thresholds (e.g. Docker Hub's 100 pulls per 6 hours limit).
| Cause | Frequency |
|---|---|
| Image name spelling typo or non-existent tag | ⭐⭐⭐⭐⭐ |
| Missing private registry authentication (imagePullSecrets) | ⭐⭐⭐⭐ |
| Exceeded public registry anonymous pull limits (rate limiting) | ⭐⭐⭐ |
Common Mistakes
- Assuming public images are immune to ImagePullBackOff (Docker Hub enforces strict rate limiting blocks on anonymous connections shareable across NAT gateways).
- Forgetting to match namespace scopes (Secrets must reside inside the same namespace as the referencing Pod to be accessible during pulls).
How to Fix
Kubernetes Operations & Verification
Configure image pull credentials in Pod configurations referencing private registry servers.
apiVersion: v1
kind: Pod
metadata:
name: private-service-pod
spec:
containers:
- name: secure-app
image: private-registry.io/org/secure-app:v1.0.0
# Reference the authentication secret
imagePullSecrets:
- name: registry-credentials-secretPlatform Specific Fixes
Log directly into nodes and use CRI tools (crictl) to pull images outside of Kubelet loop.
# 1. Inspect local containerd runtime events
journalctl -u containerd -n 50
# 2. Test pulling using CRI command line
crictl pull private-registry.io/org/secure-app:v1.0.0Best Practices
- Verify that the container image is built and successfully pushed to the registry before triggering cluster deployment pipelines.
- Adopt custom local container registries (like Harbor) to cache public hub images within cluster networks.
Frequently Asked Questions (FAQ)
Q: What is the difference between ErrImagePull and ImagePullBackOff?
ErrImagePull is the initial failure exception when trying to fetch the image. ImagePullBackOff is the subsequent state where Kubernetes backs off and waits before trying again to avoid flooding the registry server.
Q: How do I configure pull credentials in Kubernetes?
First, create a secret: 'kubectl create secret docker-registry regcred --docker-server=<registry-url> --docker-username=<user> --docker-password=<pass>'. Then, reference it in your Pod template spec under 'imagePullSecrets: - name: regcred'.
Q: Why do I get this error for public images like Nginx?
This is usually caused by Docker Hub's anonymous rate limits. If your cluster shares a NAT gateway IP with other nodes, the rate limit might be exhausted. Authenticating with Docker Hub resolves this.
Q: How do I inspect image pull details at the runtime level?
In Kubernetes v1.36, you can log into the node and use the CRI CLI utility 'crictl pull <image>' to test pulling the image directly outside of Kubernetes.