What the error looks like
The pod status, and the real reason in its Events:
NAME READY STATUS RESTARTS AGE
web-xxxx 0/1 ImagePullBackOff 0 2m
# kubectl describe pod web-xxxx -> Events:
Failed to pull image "myrepo/web:v2":
rpc error: code = NotFound desc = ... manifest unknown
Back-off pulling image "myrepo/web:v2"Read the Events line. manifest unknown / not found = bad name or tag; pull access denied / no basic auth = a private registry needing credentials; timeout = the registry is unreachable.
Why it happens
Wrong image name or tag
A typo, or a tag that was never pushed or has been deleted.
Private registry, no imagePullSecrets
The kubelet has no credentials, so the pull is denied.
Registry unreachable or rate-limited
Network/firewall blocks the registry, or Docker Hub rate-limits anonymous pulls.
Architecture mismatch
The image has no variant for the node architecture (arm64 vs amd64).
Diagnose it in three steps
Read the pod Events
kubectl describe pod web-xxxx
# the Events at the bottom name the exact pull failure.Verify the image:tag exists
docker pull myrepo/web:v2 # does it resolve from where you are?
# typo, wrong registry, or missing tag will fail here too.Check credentials for a private registry
kubectl get secret regcred -o yaml # exists and referenced?
kubectl get pod web-xxxx -o jsonpath='{.spec.imagePullSecrets}'Fix the reference, add a pull secret, pin the tag
Correct the image name and tag, and for a private registry create an image pull secret and reference it. Pin a specific tag or digest so pulls are reproducible.
# create credentials for a private registry
kubectl create secret docker-registry regcred \
--docker-server=registry.example.com \
--docker-username=USER --docker-password=PASS
# reference it in the pod / deployment spec
spec:
imagePullSecrets:
- name: regcred
containers:
- name: web
image: registry.example.com/web:v2 # a specific tag, not latestFor Docker Hub rate limits, authenticate pulls with an imagePullSecret or mirror the image into a registry you control - anonymous pulls are limited by IP.
Verify the image before the rollout
A pod that cannot pull its image is a deploy that should never have started. On your own servers, Infraveil checks a rollout and surfaces a failed pull with its context before it takes traffic - and keeps registry credentials least-privilege and recorded, so a bad tag or missing secret is caught early, not in a stuck pod.
Frequently asked questions
What is the difference between ImagePullBackOff and ErrImagePull?
ErrImagePull is the immediate pull failure; ImagePullBackOff is the state Kubernetes enters afterward, backing off and retrying with increasing delay. Two stages of the same problem - check the pod Events for the underlying reason.
How do I pull from a private registry?
Create a docker-registry secret (kubectl create secret docker-registry regcred ...) and reference it with imagePullSecrets in the pod spec or service account. Without it the kubelet has no credentials and the pull is denied.
Why am I getting Docker Hub rate-limit errors?
Docker Hub limits anonymous pulls by IP, which a busy cluster hits fast. Authenticate pulls with an imagePullSecret, mirror the image to your own registry, or pin images in a registry you control.
Why is using the latest tag risky?
latest is mutable, so a node may pull a tag that moved or was removed and you cannot tell which build is running. Pin a specific immutable tag or a digest so pulls are stable and reproducible.
Client-side, no signup — they run in your browser.