What is the difference between ErrImagePull and ImagePullBackOff?

ErrImagePull is the immediate pull failure; ImagePullBackOff is the backoff state between retries of that failure. They are two phases of the same problem, and the diagnostic information lives on the ErrImagePull event.

How do I see the real reason behind ImagePullBackOff?

Run `kubectl describe pod ` and read the Events section at the bottom. The registry's actual error is quoted there: "manifest unknown", "unauthorized", "toomanyrequests", or a network timeout, and each maps to a different fix.

Does deleting the pod fix ImagePullBackOff?

Only after you fix the underlying cause. Deleting the pod just resets the backoff timer and forces an immediate retry: useful to skip the up-to-5-minute wait, useless if the image reference or credentials are still wrong.

Why does ImagePullBackOff happen only on some nodes?

Because image pulls happen per node. A node with the image cached runs the pod fine while a fresh node has to pull and hits the rate limit or network problem. Node-specific egress rules and stale credentials on particular nodes produce the same pattern.

How do I prevent Docker Hub rate limits from breaking my cluster?

Authenticate pulls with a paid account, mirror the images you depend on into your own registry (ECR, GCR, Artifactory), or run a pull-through cache. Anonymous pulls from cluster NAT gateways share one IP-based quota and will keep hitting the limit.

Error reference

ImagePullBackOff in Kubernetes: What It Means and How to Fix It

Updated July 27, 2026

In short

ImagePullBackOff means the kubelet failed to pull your container image and is backing off between retries. In practice there are only four causes: a wrong image name or tag, missing or expired registry credentials (imagePullSecrets), a registry rate limit, or a network/DNS problem between the node and the registry. Run kubectl describe pod <pod> and read the Events section: it names the exact failure.

start here

kubectl describe pod <pod-name> | grep -A 10 Events

Diagnosis

Causes at a glance

Cause	How to recognize it	Fix
Wrong image name or tag	Events show "manifest unknown" or "not found"	Fix the image reference in the pod spec; verify with `docker pull` locally
Missing or expired registry credentials	Events show "unauthorized" or "authentication required"	Create/refresh the pull secret and reference it in imagePullSecrets
Registry rate limit	Events show "toomanyrequests" (Docker Hub free tier)	Authenticate pulls, mirror the image to your own registry, or upgrade the plan
Network or DNS failure to the registry	Events show "i/o timeout" or "no such host"	Check node egress, proxy settings, and cluster DNS; test from the node

What ImagePullBackOff actually is

ImagePullBackOff is not the error itself. It is the waiting state after the error. The kubelet first fails with ErrImagePull, then retries with exponential backoff (10s, 20s, 40s… capped at 5 minutes). The pod shows ImagePullBackOff between attempts, which is why the status seems to flap between the two.

That distinction matters for debugging: the useful information is attached to the original pull failure, not the backoff state. Always read the Events, not just the status column.

kubectl get pods
kubectl describe pod <pod-name>
# Events:
#   Failed to pull image "myapp:lastest": manifest unknown

Step 1

Step 1: read the exact failure from Events

The Events section of kubectl describe pod contains the registry's actual response. Match it against the causes table above: "manifest unknown" is a bad reference, "unauthorized" is credentials, "toomanyrequests" is a rate limit, "i/o timeout" is network.

Step 2

Step 2: verify the image reference

Typos in the tag ("lastest") and images pushed to a different registry path than the deployment references are the most common cause in CI-built clusters. Verify the exact reference exists from a machine with registry access.

# does the image actually exist under this exact name?
docker pull registry.example.com/team/myapp:1.4.2
# or without pulling:
docker manifest inspect registry.example.com/team/myapp:1.4.2

Step 3

Step 3: fix credentials with imagePullSecrets

Private registries need a pull secret in the same namespace as the pod, and the pod (or its ServiceAccount) must reference it. Secrets are namespaced: a secret in default does nothing for a pod in production.

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=ci-bot --docker-password=$TOKEN \
  -n production

# pod spec:
#   imagePullSecrets:
#     - name: regcred

Step 4

Step 4: after the fix

Kubernetes retries on its own, but the backoff can make that feel slow (up to 5 minutes). Delete the pod to force an immediate retry once the underlying cause is fixed: the Deployment recreates it instantly.

kubectl delete pod <pod-name>  # deployment recreates it and pulls again

Beyond the one-off fix

Debugging one pod is a kubectl session. Knowing which of your services hit ImagePullBackOff this week (and whether an AI agent changed the image reference that caused it) is observability plus an audit trail. Nexus captures every change agents and humans ship, so "what broke this deployment" has an answer attached.

Explore Swfte Nexus

Common questions

What is the difference between ErrImagePull and ImagePullBackOff?: ErrImagePull is the immediate pull failure; ImagePullBackOff is the backoff state between retries of that failure. They are two phases of the same problem, and the diagnostic information lives on the ErrImagePull event.
How do I see the real reason behind ImagePullBackOff?: Run `kubectl describe pod <pod-name>` and read the Events section at the bottom. The registry's actual error is quoted there: "manifest unknown", "unauthorized", "toomanyrequests", or a network timeout, and each maps to a different fix.
Does deleting the pod fix ImagePullBackOff?: Only after you fix the underlying cause. Deleting the pod just resets the backoff timer and forces an immediate retry: useful to skip the up-to-5-minute wait, useless if the image reference or credentials are still wrong.
Why does ImagePullBackOff happen only on some nodes?: Because image pulls happen per node. A node with the image cached runs the pod fine while a fresh node has to pull and hits the rate limit or network problem. Node-specific egress rules and stale credentials on particular nodes produce the same pattern.
How do I prevent Docker Hub rate limits from breaking my cluster?: Authenticate pulls with a paid account, mirror the images you depend on into your own registry (ECR, GCR, Artifactory), or run a pull-through cache. Anonymous pulls from cluster NAT gateways share one IP-based quota and will keep hitting the limit.