kubernetes CrashLoopBackOff image pull backoff

Legacy context

Legacy context. This site is an independent educational reference for software operations and technical documentation. The material presented here is drawn from preserved historical excerpts, offered for study and general understanding of development practices and system administration topics.

The archive focuses on technical notes and operational guidance, including discussions of cloud-based technologies and software engineering patterns. Content is provided for educational purposes only and does not represent an active service, product, or company. No current offerings, certifications, or support are implied.

Readers are encouraged to treat all examples as illustrative. While the excerpts reference specific tools and approaches, this site does not verify their current applicability or endorse any particular vendor. For production decisions, consult up-to-date official documentation and relevant community resources.

Kubernetes CrashLoopBackOff and Image Pull Backoff: A Practical Troubleshooting Guide. When a Kubernetes pod fails to start, you will often see one of two recurring statuses: `CrashLoopBackOff` or `ImagePullBackOff`. These are not interchangeable, but they frequently appear together in the same workload, and misdiagnosing one as the other wastes significant debugging time. This guide explains the difference, walks through concrete diagnostic steps, and provides a compact reference for the most common failure modes.

Understanding the Two Backoff States. `ImagePullBackOff` is a kubelet state that occurs when the container runtime cannot fetch the container image from a registry. The kubelet retries with an exponential backoff (starting around 10 seconds, doubling up to 300 seconds). The pod remains in `Pending` or `ContainerCreating` while this happens.

`CrashLoopBackOff` is a different state: the image was pulled successfully, the container started, but the process inside exited immediately or repeatedly. The kubelet restarts the container with the same exponential backoff. The pod may show `Running` briefly, then flip to `CrashLoopBackOff`.

A pod can show both states sequentially. For example, if your image tag is wrong, you get `ImagePullBackOff`. After you fix the tag, the container starts but crashes due to a missing environment variable, producing `CrashLoopBackOff`.

The fastest way to distinguish the two is to describe the pod:

kubectl describe pod <pod-name> -n <namespace>

Look at the `Events` section at the bottom. You will see lines like:. - `Failed to pull image "nginx:lates"` – typo in tag, causes `ImagePullBackOff`

• `Back-off pulling image` – registry authentication or network issue
• `Error: failed to start container` – usually a runtime issue, not image pull
• `Started container` followed by `Error from server: ...` – indicates crash after start.

Decision criteria: if the event mentions `pull`, `image`, `registry`, or `manifest`, treat it as an image pull problem. If the event mentions `exec`, `exit code`, `signal`, or `started container`, treat it as a crash problem.

Common Failure Modes

1. Typo in image name or tag – The most frequent cause. `nginx:lates` instead of `nginx:latest`. Kubernetes does not validate tags; it simply attempts to pull and fails.
2. Private registry authentication – If your image is in a private registry (e.g., AWS ECR, Google Artifact Registry, or a self-hosted Harbor), the kubelet needs credentials. These are usually provided via an `imagePullSecret` attached to the service account or pod spec. Without it, you get `unauthorized: authentication required`.
3. Network egress restrictions – Nodes may not have outbound internet access, or a corporate proxy blocks registry endpoints. Check node-level network policies and DNS resolution.
4. Registry rate limiting – Docker Hub, for example, limits anonymous pulls. If many pods pull the same image simultaneously, you may see `toomanyrequests`.
5. Manifest unknown – The image exists but the specific tag or digest does not. This happens with mutable tags that were overwritten or deleted.

Concrete Diagnostic Commands

Check the exact image reference in the pod spec
kubectl get pod <pod-name> -n <namespace> -o jsonpath='{.spec.containers[*].image}'
Manually pull the image on a node (if you have SSH access)
This isolates the problem from Kubernetes
docker pull <image>:<tag>
Check imagePullSecrets on the service account. kubectl get serviceaccount default -n <namespace> -o yaml.