Kubernetes ImagePullBackOff and ErrImagePull: How to Fix

Your pod is stuck before it even runs:

NAME                     READY   STATUS             RESTARTS   AGE
api-6c4b9d7f8-nq2lm      0/1     ImagePullBackOff   0          90s

ErrImagePull is the first failure; ImagePullBackOff is Kubernetes backing off and retrying it. Either way the meaning is the same: the image was never downloaded, so the container can't start. Unlike CrashLoopBackOff (the app runs and dies), here nothing has run at all. The reason is always in the pod's events.

Step 1: Read the real error

kubectl describe pod <pod>     # scroll to Events — the exact pull error is there

You'll see one of a few clear messages. Each points at a different cause.

Cause 1: Wrong image name or tag

The most common by far. Failed to pull image ... not found means the repository or tag doesn't exist — usually a typo, or a :latest that was never pushed, or a tag that was deleted.

docker pull myrepo/api:1.4.2     # reproduce it yourself — does the tag actually exist?

Fix the image: field to a tag that exists. Avoid :latest in manifests; pin a real version so this can't drift.

Cause 2: A private registry with no credentials

pull access denied or unauthorized means the image is private and the cluster has no login. Create a pull secret and reference it in the pod spec:

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=USER --docker-password=TOKEN

spec:
  imagePullSecrets:
    - name: regcred       # the pod won't use the secret unless you name it here

Cause 3: Docker Hub rate limits

toomanyrequests or "You have reached your pull rate limit" hits anonymous pulls on Docker Hub. Authenticate the node/cluster to Docker Hub with a pull secret (as above), or mirror the image to a registry you control.

The checklist

1. kubectl describe pod <pod> and read the Events — they name the exact cause.
2. "not found" → fix the image name/tag; reproduce with docker pull.
3. "unauthorized / access denied" → create a docker-registry secret and list it under imagePullSecrets.
4. "toomanyrequests" → authenticate to Docker Hub or use your own registry mirror.
5. Pin real version tags instead of :latest so pulls stay predictable.

Frequently Asked Questions

What's the difference between ErrImagePull and ImagePullBackOff?

ErrImagePull is the first failed pull attempt; ImagePullBackOff is Kubernetes backing off and retrying it. The underlying cause is the same.

How do I pull from a private registry in Kubernetes?

Create a docker-registry Secret with your credentials and reference it under imagePullSecrets in the pod spec — the pod won't use it otherwise.

Why do I see "toomanyrequests" when pulling an image?

That's Docker Hub's anonymous pull rate limit. Authenticate the pull with a secret, or mirror the image to a registry you control.