In this article
ImagePullBackOff occurs before application startup: the kubelet cannot obtain an image and retries with backoff. Start with Pod events, the image reference and registry credentials. CUDA settings or extra VRAM cannot repair an unavailable image manifest.
ImagePullBackOff occurs before application startup: the kubelet cannot obtain an image and retries with backoff. Start with Pod events, the image reference and registry credentials. CUDA settings or extra VRAM cannot repair an unavailable image manifest.
Locate the first pull failure
Save the effective Pod image reference, namespace, ServiceAccount and events. The final BackOff message often hides the original Failed pull error: invalid naming, missing access, DNS or certificate failure. Identify the pulling node. A successful docker pull on a laptop establishes access from a different environment with different credentials. Keep full authorization data out of the report; the error category and Secret name are sufficient evidence.
Check imagePullSecrets scope
The Secret must exist in the Pod’s namespace and contain suitable registry credentials. imagePullSecrets belong to the Pod; a ServiceAccount can also attach them to newly created Pods. Match the registry and image path with the authorization entry. FailedToRetrieveImagePullSecret means the referenced Secret could not be retrieved. That differs from credentials being retrieved successfully but rejected by the registry, and the correction should preserve that distinction.
Separate two similar cases
In an example, a Pod in namespace inference references regcred, but that Secret exists only in namespace tools. Editing its username cannot repair the missing namespace reference. In another case, the Secret is found but the requested tag does not exist. Check image publication and the reference instead. These namespace names explain the mechanism; they do not describe an existing Retrivium cluster.
| Event evidence | Investigation direction |
|---|---|
| Secret not found | Namespace and reference |
| Unauthorized | Credentials and registry scope |
| Unknown manifest | Repository, tag or digest |
| TLS/DNS error | Node networking and trust |
Include pull policy
Preserve imagePullPolicy and the effective image digest. Policy is set when an object is created and does not necessarily change automatically when a tag changes. A cached image on one node can hide a defect that appears on another node without the cache. Verify the correction where a pull actually occurs. Do not delete every local image without assessing neighboring workloads and the ability to download again.
Confirm a new instance starts
After correction, observe successful pulling and container creation, then independently verify application startup. Clearing ImagePullBackOff does not establish GPU functionality or model readiness. Retain the reference, digest, namespace, credential source without its value, and before/after events. This artifact distinguishes a recurring registry problem from a failure inside an already running application. A long backoff does not mean Kubernetes has stopped trying, so allow for the retry schedule when observing recovery.
Related operational reading: vllm docker first launch; software stack reproducibility.