`ImagePullBackOff` Is Usually Kubernetes Telling You the Image Name, Tag, or Registry Auth Does Not Match Reality Even if Your YAML Looks Confident

Why this error matters: ImagePullBackOff is often one of the cleanest Kubernetes failures you will ever get. The cluster is telling you it cannot fetch the image. The trick is to stop reading only the status and inspect the exact reason.

When a deployment never becomes ready and kubectl get pods shows:

ImagePullBackOff

the actual root cause is usually one of a few things:

1. wrong image name
2. wrong tag
3. private registry credentials missing
4. image does not exist in the registry you think it does
5. node cannot reach the registry

Start with describe, not guesswork

Run:

kubectl describe pod my-pod -n my-namespace

Then scroll to the Events section. That is where Kubernetes usually says the useful part, such as:

• manifest unknown
• pull access denied
• unauthorized
• repository does not exist

That message is far more valuable than the high-level ImagePullBackOff status.

Check the image reference in the workload

Read what the deployment actually says:

kubectl get deployment my-app -n my-namespace -o yaml | grep image:

Verify:

1. repository path is correct
2. tag exists
3. registry hostname is right

It is common to assume an image was pushed as:

ghcr.io/acme/api:latest

when the cluster is actually trying to pull:

ghcr.io/acme/backend:latest

If the registry is private, check the pull secret

List secrets:

kubectl get secrets -n my-namespace

Inspect the service account if you expect an imagePullSecret there:

kubectl get serviceaccount default -n my-namespace -o yaml

If needed, attach a secret in the pod spec:

imagePullSecrets:
  - name: regcred

Or create one:

kubectl create secret docker-registry regcred \
  --docker-server=ghcr.io \
  --docker-username=YOUR_USER \
  --docker-password=YOUR_TOKEN \
  [email protected] \
  -n my-namespace

Confirm the image actually exists

Before blaming Kubernetes, confirm the CI pipeline really pushed the tag you referenced. A very normal failure pattern is:

1. deployment updated to :2026-05-28-1234
2. CI failed before pushing
3. cluster keeps trying to pull a tag that was never published

That is not a cluster mystery. That is a release mismatch.

Force a clean retry after fixing it

Once the image ref or secret is corrected:

kubectl rollout restart deployment/my-app -n my-namespace
kubectl get pods -n my-namespace -w

Watch the next pod come up instead of assuming the old backoff state will heal by itself.

Final recommendation

Treat ImagePullBackOff as a registry truth problem. Use kubectl describe, verify the real image reference, confirm the tag exists, and check pull secrets before touching unrelated deployment settings.

Sources

• Kubernetes images documentation
• Kubernetes pull image private registry task