Kubernetes Pod Stuck in ImagePullBackOff

The kubelet cannot pull your container image. Almost always one of four things: wrong tag, private registry without credentials, or a rate limit.

What you'll see

Root causes

Tag does not exist

Typo in the tag, or the image was never pushed. 'manifest unknown' in events confirms it.

Missing registry credentials

Private registry without an imagePullSecret. Events show 'unauthorized: authentication required'.

Docker Hub rate limit

Anonymous pulls are limited; events show 'toomanyrequests'. Common on clusters pulling public images.

Fix it

  1. Verify the image exists exactly as written
    docker manifest inspect registry.example.com/app:v1.2.3
  2. Create a pull secret for private registries
    kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=you --docker-password=$PAT
  3. Attach it to the pod spec
    imagePullSecrets:
  - name: regcred
  4. Check the exact pull error
    kubectl describe pod <pod> | grep -A3 Events

Field note

For rate limits, host a cached copy of base images in your own registry or use a pull-through cache. It removes the whole class of problem.

Common questions

What's the difference between ImagePullBackOff and ErrImagePull?

ErrImagePull is the live failure on the current attempt; ImagePullBackOff means the kubelet has given up for now and is waiting to retry with exponential backoff. Same causes, different phase — both point at the pull, not the app.

The image exists locally — why is Kubernetes still failing to pull?

imagePullPolicy: Always (the default for :latest tags) forces a registry pull even when the image is present on the node. Use a pinned tag with IfNotPresent, or a local registry for internal images.

Related fixes

Ship it right the first time

Kustomize base with probes, PDBs, and zero-downtime rollouts already wired.

Kubernetes Production Blueprints — $27 →

One-time. Yours to modify. Instant download from the NinjaOps template store.