Kubernetes "ImagePullBackOff" - Diagnose and Fix Image Pulls

ImagePullBackOff is the back-off state a pod enters after the kubelet repeatedly failed to pull its image. It is the symptom; the real cause is in the ErrImagePull event just before it.

What this error means

A pod stays out of Running with STATUS: ImagePullBackOff. kubectl describe pod shows repeated failed pull attempts with growing back-off delays. The pod never starts because its image never lands.

NAME                   READY   STATUS             RESTARTS   AGE
api-7d9f8c6b54-2xk9p    0/1     ImagePullBackOff   0          90s

# kubectl describe pod:
Failed to pull image "myrepo/api:latest": ... not found

Common causes

Wrong image name or tag

A typo in the repository, a tag that was never pushed, or a :latest that no longer exists means there is nothing to pull. This is the most common cause.

Private registry without credentials

The image is private and the pod has no imagePullSecrets, so the registry returns an auth error and the kubelet backs off.

Registry unreachable or rate-limited

Network/DNS problems, a down registry, or Docker Hub rate limits prevent the pull. The network ones often clear on their own.

How to fix it

Read the real reason from the pod events

The describe output names the exact failure - not found, unauthorized, or a network error - which tells you which fix applies.

kubectl describe pod <pod> | sed -n '/Events/,$p'

Fix the image reference

1. Confirm the image and tag exist in the registry (docker manifest inspect <image>).
2. Avoid :latest in deploys - pin an immutable tag or digest pushed by CI.
3. Make sure the registry host in the reference is correct.

Provide pull credentials for private images

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username="$REG_USER" --docker-password="$REG_TOKEN"
# then reference it in the pod spec under imagePullSecrets

How to prevent it

• Deploy immutable tags or digests, never floating :latest.
• Attach imagePullSecrets (or a node-level credential) for private registries.
• Mirror or cache base images to avoid registry rate limits.

Frequently asked questions

Related guides