Kubernetes ImagePullBackOff: The 5 Real Causes (only one is a typo)
⏱️ 2 min read
ImagePullBackOff is Kubernetes retrying an image pull that failed. The pod's events hold the actual registry error; kubectl describe pod and read the Failed line — it names the exact cause. Here are the five that cover nearly everything.
1. The tag doesn't exist (the typo)
manifest unknown or not found: you pushed :v1.2.1 and the manifest says :v1.2.0, or CI built an image that never actually got pushed (pipeline failed after the build step). Verify with docker manifest inspect <image> from a machine with registry access.
2. No credentials / wrong secret
pull access denied: private registry, and the pod spec lacks imagePullSecrets, or the secret exists in the wrong namespace. The secret must live in the pod's namespace, and its name must match. Also check expiry — some registries (ECR) issue 12-hour tokens that CI refreshes but stored secrets don't.
3. Rate limits
toomanyrequests: Docker Hub's anonymous pull limits. Node-level caching (a pull-through cache or pre-pulled images) is the durable fix; in the meantime a paid/authenticated account raises the ceiling.
4. Wrong registry architecture
no matching manifest for linux/arm64: you built amd64 and scheduled onto an ARM node (or Graviton/Apple Silicon clusters). Multi-arch builds with docker buildx --platform end this class of failure.
5. The image name itself is malformed
A leading/trailing space in the YAML, a missing registry host (so nginx resolves to Docker Hub when you meant your internal registry), or a doubled tag. Read the error string literally — it echoes exactly what was requested.
Speed trick
Iterating in a sandbox instead of prod: a small DOKS cluster gives you a real kubelet to fail against, with none of the stakes.