LogLens AI / Errors / ImagePullBackOff

ImagePullBackOff / ErrImagePull: how to fix it

TL;DR. ImagePullBackOff (after ErrImagePull) means kubelet could not pull the container image, so it backs off retrying. The image name/tag is wrong, the image doesn't exist, or the registry needs credentials.

What causes ImagePullBackOff

A typo in the image name or tag; the tag was never pushed; a private registry with no imagePullSecret; rate-limited or unreachable registry; or wrong architecture.

How to diagnose it

Run kubectl describe pod <pod> and read the Events — it states the exact pull error (manifest unknown, unauthorized, no such host). Try pulling the image manually with docker pull <image>.

How to fix ImagePullBackOff

  1. Verify the image name and tag. Confirm the repository and tag exist and were pushed — manifest unknown means the tag is missing.
  2. Add registry credentials. For private registries, create an imagePullSecret and reference it in the pod spec (unauthorized means missing/invalid creds).
  3. Check registry reachability. Fix DNS/network to the registry and watch for Docker Hub rate limits (toomanyrequests) — authenticate or mirror.

Example log line

Failed to pull image "myrepo/app:v2": rpc error: code = NotFound ... manifest unknown
Reason: ImagePullBackOff

How LogLens detects ImagePullBackOff

LogLens flags image-pull failures across your cluster's events so you spot a bad deploy immediately. LogLens AI is a free, self-hosted AI log analyzer that surfaces lines like this automatically, groups them into one incident, and explains them in plain language.

Install LogLensSee the tour

Related errors

FAQ

What is the difference between ErrImagePull and ImagePullBackOff?

ErrImagePull is the first failed pull attempt; ImagePullBackOff is Kubernetes backing off before retrying after repeated failures. Same root cause.

How do I fix 'unauthorized' when pulling an image?

Create a Kubernetes imagePullSecret with your registry login and reference it under imagePullSecrets in the pod/deployment spec.