Fix: ImagePullBackOff and ErrImagePull in Kubernetes

The pod never starts, and kubectl get pods shows one of these statuses:

NAME                    READY   STATUS             RESTARTS   AGE
web-6f7c9d4b8b-k2xpl    0/1     ErrImagePull       0          12s
web-6f7c9d4b8b-k2xpl    0/1     ImagePullBackOff   0          45s

ErrImagePull is the failed attempt; ImagePullBackOff means the kubelet is waiting before trying again. It keeps retrying with a growing delay, up to five minutes between attempts, so a permanent problem never fixes itself.

Find the real reason

kubectl describe pod web-6f7c9d4b8b-k2xpl -n shop

At the bottom, the events show the image and the registry’s answer. The kubelet’s messages have this form:

Normal   Pulling  kubelet  Pulling image "registry.example.com/shop/web:1.4.0"
Warning  Failed   kubelet  Failed to pull image "registry.example.com/shop/web:1.4.0": <reason from the runtime>
Warning  Failed   kubelet  Error: ErrImagePull
Normal   BackOff  kubelet  Back-off pulling image "registry.example.com/shop/web:1.4.0"
Warning  Failed   kubelet  Error: ImagePullBackOff

The text after Failed to pull image ...: comes from the container runtime and the registry, and it tells you which cause below applies.

Cause 1: wrong image name or tag (most common)

Typos, a tag that was never pushed, or a missing registry prefix. The reason usually mentions not found or manifest unknown. A name without a registry means Docker Hub: busybox is short for docker.io/library/busybox:latest.

1. Copy the exact image string from the event.
2. Check it from a machine that can reach the registry, for example with docker pull, podman pull or crane manifest.
3. Fix the tag in your manifest or Helm values and apply again, or roll back with kubectl rollout undo deployment/web -n shop.

Cause 2: private registry without credentials

The reason mentions unauthorized, authentication required or pull access denied. Create a registry Secret in the same namespace as the pod and reference it:

kubectl create secret docker-registry regcred -n shop \
  --docker-server=registry.example.com \
  --docker-username=ci-puller \
  --docker-password='CHANGE_ME'

spec:
  imagePullSecrets:
  - name: regcred
  containers:
  - name: web
    image: registry.example.com/shop/web:1.4.0

Instead of adding it to every pod, you can attach it to the namespace’s service account: kubectl patch serviceaccount default -n shop -p '{"imagePullSecrets":[{"name":"regcred"}]}'. Prefer a read-only pull token over a personal password.

Cause 3: registry rate limits

Docker Hub limits anonymous pulls. The reason then mentions toomanyrequests. Authenticate with a pull secret, use a mirror or pull-through cache, or copy the image into your own registry.

Cause 4: the node cannot reach the registry

Timeouts, connection refused, DNS failures or x509: certificate signed by unknown authority point at the node, not Kubernetes. The pull is done by the container runtime on the node, so proxy settings, firewall rules and trusted CA certificates must be configured there. Test from the node itself, for example with crictl pull.

Cause 5: wrong CPU architecture

An image built only for amd64 cannot run on arm64 nodes. Depending on the runtime, this shows up as a pull error saying no matching manifest exists for the platform, or as a container that starts and immediately fails with exec format error. Build multi-architecture images or add a nodeSelector on kubernetes.io/arch.

Related: InvalidImageName

If the status is InvalidImageName, the image string cannot even be parsed (for example uppercase letters or a stray space). Fix the string; retrying will not help.

After the fix

Once the cause is fixed, a Deployment picks up the corrected manifest automatically. For a pod still backing off with an unchanged spec (for example after you created a missing pull secret), delete the pod so its controller recreates it immediately, or wait for the next retry.

Official documentation

• Images
• Debug Pods