Kubernetes: Pod stuck in ImagePullBackOff

Hi, it's BlueByte. A Pod that never leaves ImagePullBackOff isn't crashing — on paper it scheduled fine, but the kubelet can't fetch the container image, so it keeps retrying and backing off. The symptom is a Pod stuck at 0/1 with STATUS: ImagePullBackOff (or ErrImagePull a moment earlier). We'll walk through what those two states mean, how to read the Events to find the real reason, fix it per cause, and keep it from coming back.

What ImagePullBackOff and ErrImagePull are telling you

Two related states show up in kubectl get pods:

NAME                    READY   STATUS             RESTARTS   AGE
web-6d4b8f9c7c-2xk9p    0/1     ImagePullBackOff   0          3m

ErrImagePull is the immediate failure: the kubelet asked the container runtime to pull the image and the pull failed. ImagePullBackOff is what follows — after repeated failures the kubelet waits before trying again, increasing the delay each time up to a five-minute cap. Neither means your application is broken. The container never started, because its image never arrived.

Why the kubelet can't pull the image

The pull fails for one of a few concrete reasons:

• The image name or registry is wrong — a typo, or a missing registry prefix so it defaults to Docker Hub.
• The tag doesn't exist — the image is real but :1.2.3 was never pushed, or you meant :1.2.3 and typed :1.23.
• The image is private and the Pod has no credentials — the registry answers with an authorization error.
• You hit a registry rate limit (Docker Hub throttles anonymous pulls), so the pull is refused for now.
• imagePullPolicy: Never is set but the image isn't already present on the node.

Read the Events to see the real reason

Don't guess — the Events at the bottom of kubectl describe name the exact failure:

kubectl describe pod web-6d4b8f9c7c-2xk9p

Events:
  Type     Reason   Age               From     Message
  ----     ------   ----              ----     -------
  Warning  Failed   30s (x4 over 2m)  kubelet  Failed to pull image "myrepo/app:1.2.3":
                                               manifest unknown: manifest unknown
  Warning  Failed   30s (x4 over 2m)  kubelet  Error: ErrImagePull
  Normal   BackOff  5s  (x6 over 2m)  kubelet  Back-off pulling image "myrepo/app:1.2.3"

The Message is the whole story. manifest unknown means the tag doesn't exist; pull access denied or unauthorized means it's private and unauthenticated; no such host means the registry name is wrong. Confirm by pulling the same image by hand from a node or your laptop:

docker pull myrepo/app:1.2.3

If that fails the same way, the problem is the image or the credentials, not Kubernetes.

Fix it by cause: name, tag, private registry

1. Wrong name or tag — verify the tag exists in the registry, then correct the reference and re-apply:

kubectl set image deployment/web app=myrepo/app:1.4.0

2. Private registry — create a pull secret and attach it to the Pod template:

kubectl create secret docker-registry regcred \
  --docker-server=registry.example.com \
  --docker-username=<user> \
  --docker-password=<token>

spec:
  imagePullSecrets:
    - name: regcred

3. Rate limited on Docker Hub — authenticate with the same secret mechanism, or mirror the image into your own registry.

A real case: a private image with no pull secret

You deploy registry.example.com/team/api:2.1.0 and the Pod sits at ImagePullBackOff. kubectl describe pod shows Failed to pull image ...: pull access denied, repository does not exist or may require authorization. The image is real and pushed, so it's authorization. You create the pull secret with kubectl create secret docker-registry regcred ..., add imagePullSecrets: [{ name: regcred }] to the Deployment's Pod template, and run kubectl rollout restart deployment/api. Within seconds the new Pod pulls the image and reaches 1/1 Running. The registry was reachable all along — the kubelet just had no credentials to present.

Confirm the Pod is actually Running

After the fix, watch the Pod come up:

kubectl get pod -l app=api -w

NAME                   READY   STATUS    RESTARTS   AGE
api-7c9d5f8b6d-abcde   1/1     Running   0          12s

1/1 and Running with no restarts means the image pulled and the container started. kubectl describe pod now shows a Pulled event instead of Failed.

Keep it from recurring

Pin images to a real, immutable tag or a digest rather than :latest, so a Pod can't land on a tag that was retagged or removed — with :latest the default imagePullPolicy is even Always, so every restart re-pulls. Store registry credentials as a Secret referenced by every workload that needs the private registry, and for Docker Hub at scale, pull through an authenticated mirror to stay under the rate limit. Validate the spec with kubectl apply --dry-run=server -f pod.yaml before rollout to catch a bad image reference early.

How this differs from CrashLoopBackOff

ImagePullBackOff happens before the container runs — the image never arrived. CrashLoopBackOff happens after: the image pulled fine, the container started, then exited repeatedly. If kubectl describe shows a Pulled event but the Pod still restarts, that's CrashLoopBackOff and you should read the container logs, not the image reference. Both use the same exponential back-off, but the cause sits on opposite sides of "did the image load."