Fixing ImagePullBackOff in Kubernetes
A pod can't start because Kubernetes can't pull its container image — the fix depends entirely on which of a handful of specific causes is actually responsible, from a typo to a private registry auth problem.
ImagePullBackOff means Kubernetes tried to pull a pod’s container image and failed, and is now backing off before retrying — the specific underlying reason is almost always visible directly in the pod’s events.
Step 1: check the exact pull error
kubectl describe pod mypodThe Events section shows the actual error from the container runtime attempting the pull — this is the single most important piece of information, since the remaining steps all depend on which specific failure this reveals.
Step 2: check for a simple image name or tag typo
Failed to pull image "myapp:v1.0.1": rpc error: ...
manifest for myapp:v1.0.1 not foundConfirm the image name and tag in the pod spec exactly match what actually exists in the registry — a surprising fraction of ImagePullBackOff cases are exactly this simple.
Step 3: check for a missing or incorrect image pull secret, for private registries
Failed to pull image: ... unauthorized: authentication requiredkubectl get pod mypod -o yaml | grep -A3 imagePullSecrets
kubectl get secret <secret-name> -o yamlA private registry requires an imagePullSecrets entry referencing valid registry credentials — confirm the secret exists in the correct namespace, is correctly referenced in the pod spec (or the associated ServiceAccount), and hasn’t expired.
Step 4: verify registry credentials are actually still valid
docker login <registry-url>
# or, for a specific stored secret:
kubectl get secret <secret-name> -o jsonpath='{.data.\.dockerconfigjson}' | base64 -dExpired or rotated registry credentials that were never updated in the corresponding Kubernetes secret produce exactly this authentication failure, even though the secret itself still exists and looks superficially correct.
Step 5: check for a network problem reaching the registry
Failed to pull image: ... context deadline exceededA timeout, rather than an explicit authentication or not-found error, points at a network path problem between the node and the registry — check for a firewall rule, a DNS resolution failure specific to the registry’s hostname, or an outage on the registry’s side.
Step 6: check the node’s own available disk space for image storage
kubectl describe node <node-name> | grep -A5 "Conditions"A node reporting disk pressure can fail to pull new images even when the pull request itself would otherwise succeed — see fixing ‘no space left on device’ from Docker image buildup for the underlying cause this often traces back to.
Step 7: verify the image actually exists in the registry, independent of Kubernetes
docker pull myapp:v1.0.1Pulling the exact same image manually, outside of Kubernetes entirely, isolates whether the problem is genuinely about the image/registry, or specific to how Kubernetes (or a specific node) is attempting the pull.
Step 8: check imagePullPolicy if testing with a locally-built image
imagePullPolicy: NeverSimilar to loading a local image into a kind cluster, a pod expecting to use a locally-available image needs imagePullPolicy: Never (or IfNotPresent) — otherwise Kubernetes will always attempt to pull from a registry, where a locally-built-only image doesn’t exist at all.
Why the exact error text is the single most useful diagnostic signal
Unlike some Kubernetes failures that require correlating several pieces of information, ImagePullBackOff’s root cause is almost always stated plainly in the pod’s events — “not found,” “unauthorized,” and “context deadline exceeded” point at three completely different fixes (a typo, a credentials problem, a network problem respectively), which is why reading that exact message first, before trying anything else, is consistently the fastest path to resolving it.