KUBERNETES POD STUCK IN IMAGEPULLBACKOFF OR ERRIMAGEPULL ------------------------------------------------------------------------ The kubelet cannot pull the image, so the container never starts. ErrImagePull is the first failure and ImagePullBackOff is the wait between retries — neither says why. The registry's own error text, printed in the pod's Events, is what identifies the cause. CONFIDENCE : high VERIFIED : 2026-08-07 (fresh, 0d old) URL : https://knowbase.sh/k/kubernetes-imagepullbackoff ERROR ------------------------------------------------------------------------ ImagePullBackOff CODES: ImagePullBackOff, ErrImagePull PROBLEM ------------------------------------------------------------------------ A pod never reaches Running. Its status alternates between ErrImagePull and ImagePullBackOff, and the restart interval grows. kubectl logs returns nothing because no container was ever created — the failure happens before the image becomes a container, so the usual log-reading reflex gives you nothing to work with. ROOT CAUSE ------------------------------------------------------------------------ 1. [primary] The image reference is wrong or the tag does not exist A typo in the repository, a tag that was never pushed, or a tag that has since been deleted or overwritten. The registry answers correctly; the reference is simply wrong. how to tell: Events show 'manifest unknown' or 'not found', and pulling the exact same reference from your own machine fails identically 2. [common] The registry is private and credentials are missing or wrong No imagePullSecrets on the pod or its ServiceAccount, a secret in the wrong namespace, or credentials that have expired. Image pull secrets are namespaced, so one that works in staging does nothing in production. how to tell: Events show '401 Unauthorized', 'pull access denied' or 'authentication required' 3. [common] The registry rate-limited the pull Docker Hub limits unauthenticated pulls to 100 per IPv4 address or IPv6 /64 subnet per six hours. A cluster behind one NAT address shares that budget across every node, so a busy cluster exhausts it without any single workload looking unusual. how to tell: Events contain 'toomanyrequests' or 'You have reached your pull rate limit' 4. [common] The node cannot reach the registry DNS failure, an egress firewall, a proxy that needs configuring on the container runtime rather than the pod, or a private registry with no route from the node subnet. how to tell: Events show 'dial tcp ... i/o timeout', 'no such host' or a TLS handshake failure 5. [edge] The image has no build for the node's architecture An amd64-only image scheduled onto an arm64 node. The reference resolves and credentials work, but the manifest list has no matching entry. how to tell: Events show 'no matching manifest for linux/arm64' or a similar platform string SOLUTION ------------------------------------------------------------------------ 1. Read the Events at the bottom of the pod description. The registry's own error text is there, and it names the cause; the pod status never does. $ kubectl describe pod -n note: Look for the Failed event from the kubelet — it quotes the runtime's message verbatim. 2. Reproduce the pull from outside the cluster with the exact same reference. This separates a wrong reference from a cluster-side problem in one step. $ crane manifest /: || docker pull /: 3. If the registry is private, create a pull secret and attach it to the pod in the same namespace as the pod. kubectl create secret docker-registry regcred \ --docker-server= \ --docker-username= \ --docker-password= \ -n note: Then reference it under spec.imagePullSecrets, or attach it to the ServiceAccount so every pod in the namespace inherits it. 4. Wire the secret into the pod spec, or the kubelet will keep pulling anonymously. spec: imagePullSecrets: - name: regcred containers: - name: app image: /: 5. If the message mentions rate limiting, authenticate rather than retry. Unauthenticated pulls share a per-IP budget across the whole cluster, so retrying makes it worse. Mirroring hot images into your own registry removes the dependency entirely. 6. Fix the reference or the credentials, then replace the pod. Editing nothing and waiting does not help — the kubelet retries with the same failing spec, backing off up to five minutes between attempts. $ kubectl rollout restart deployment/ -n VERIFY: kubectl describe pod shows a 'Successfully pulled image' event and the pod reaches Running; kubectl get pod reports a stable RESTARTS count. FALLBACK: Where the registry is genuinely unreachable from the cluster — an air-gapped environment, for example — pre-load the image onto the nodes and set imagePullPolicy to IfNotPresent so the kubelet uses the local copy. APPLIES TO ------------------------------------------------------------------------ Kubernetes: 1.20 and later (ImagePullBackOff is a Waiting-state reason surfaced by the kubelet, not a Pod phase.) kubelet: 1.20 and later (Pull retry delay grows to a compiled-in ceiling of 300 seconds.) runtimes: containerd, CRI-O platforms: linux/amd64, linux/arm64 NOT APPLICABLE TO ------------------------------------------------------------------------ - CrashLoopBackOff, where the image pulled successfully and the container starts then exits - CreateContainerConfigError, where a referenced ConfigMap or Secret is missing - ErrImageNeverPull, which means imagePullPolicy is Never and the image is absent from the node - Pods stuck in Pending, which is a scheduling problem and never reaches the pull stage EVIDENCE ------------------------------------------------------------------------ 1. Images — ImagePullBackOff https://kubernetes.io/docs/concepts/containers/images/ The Kubernetes Authors | official-docs | read 2026-08-07 supports: The definition of ImagePullBackOff, that an invalid image name and a private registry without an imagePullSecret are its named causes, and that the retry delay grows to a compiled-in ceiling of 300 seconds. 2. Pull an Image from a Private Registry https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/ The Kubernetes Authors | official-docs | read 2026-08-07 supports: That a docker-registry Secret is the mechanism for authenticated pulls and that it is referenced from the pod through imagePullSecrets. 3. Docker Hub pull usage and limits https://docs.docker.com/docker-hub/usage/pulls/ Docker Inc. | official-docs | read 2026-08-07 supports: The unauthenticated pull ceiling of 100 per IPv4 address or IPv6 /64 subnet per six hours, which is why a NATed cluster exhausts the budget collectively. 4. Debug Pods https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/ The Kubernetes Authors | official-docs | read 2026-08-07 supports: That describing the pod and reading its recent events is the first diagnostic step, which is where the registry's own error text appears. CONFIDENCE ------------------------------------------------------------------------ high — The status definition, the retry ceiling and the named causes come from Kubernetes' own image documentation, and the pull-limit figures from Docker's published table. The per-cause discriminators are the runtime's own error strings as surfaced in pod events rather than claims any single document makes about diagnosis. ------------------------------------------------------------------------ knowbase 0.1.0 — CC-BY-4.0