Fixing ImagePullBackOff in Kubernetes

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 mypod

The 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 found

Confirm 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 required

kubectl get pod mypod -o yaml | grep -A3 imagePullSecrets
kubectl get secret <secret-name> -o yaml

A 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 -d

Expired 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 exceeded

A 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.1

Pulling 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.

Run the comparison from the affected node or an environment with equivalent DNS, proxy, certificates, architecture, and identity. A successful laptop pull does not prove the node can reach the registry. Avoid printing decoded pull-secret contents into terminals or logs; inspect metadata and test through a short-lived, least-privilege credential instead.

Step 8: check imagePullPolicy if testing with a locally-built image

imagePullPolicy: Never

Similar 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.

Check platform, certificates, and immutable identity

An image can exist and authenticate correctly yet lack a manifest for the node’s operating system or CPU architecture. Inspect the registry manifest list and compare it with the scheduled node. Certificate errors usually mean an incomplete trust chain, hostname mismatch, or an intercepted registry connection; do not permanently mark a production registry insecure to hide the failure.

Prefer an approved image digest in production. Tags can be moved or can point at a different manifest than the one tested. Confirm the pod’s resolved imageID after recovery and compare it with the promoted digest. For short-lived cloud registry credentials, use the provider’s supported node or workload identity integration and monitor expiration rather than copying personal login tokens into namespace Secrets.

After fixing the cause, watch events and the owning rollout, not only a single retry:

kubectl get events --for pod/mypod --watch
kubectl rollout status deployment/myapp

Verify all nodes that may schedule the workload can pull the image. A cached copy on one node can conceal a registry or credential problem that returns during rescheduling.

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.

Related:

Sources: