What's the difference?
CrashLoopBackOff vs ImagePullBackOff
Two pods stuck at 0/1, both in a back-off. Watch how far each one gets before it fails.
Side by side
One ran and died. One never started.
Pod A: the container starts, turns green for a moment, then exits. The kubelet waits and restarts it: CrashLoopBackOff, restart count rising. Pod B: the runtime asks the registry for the image and is refused. Nothing is ever started: ErrImagePull, then ImagePullBackOff, restart count still zero.
- failure
- back-off
- restart
- pull retry
Side by side
One ran and died. One never started.
Pod A: the container starts, turns green for a moment, then exits. The kubelet waits and restarts it: CrashLoopBackOff, restart count rising. Pod B: the runtime asks the registry for the image and is refused. Nothing is ever started: ErrImagePull, then ImagePullBackOff, restart count still zero.
- failure
- back-off
- restart
- pull retry
- CrashLoopBackOffThe pod turns green first. The process ran, so there are logs and an exit code.
- ImagePullBackOffThe registry lights up red. The pod never turns green, and there is nothing to read logs from.
How to tell them apart
| Question | CrashLoopBackOff | ImagePullBackOff |
|---|---|---|
| How far it gets | Image pulled, container started, process exited | Image never pulled, container never started |
| Where it breaks | Your application or its configuration | The registry, the image name or the credentials |
| RESTARTS column | Climbs with every attempt | Stays at 0 |
| Application logs | Yes: kubectl logs --previous | None. The app never ran |
| Where to look | Exit code under Last State, then the previous logs | The Events in kubectl describe pod: the pull error message |
| Typical fix | Fix the config, command or dependency the app needs | Fix the image tag, add imagePullSecrets, or wait out a rate limit |
How far it gets
- CrashLoopBackOff
- Image pulled, container started, process exited
- ImagePullBackOff
- Image never pulled, container never started
Where it breaks
- CrashLoopBackOff
- Your application or its configuration
- ImagePullBackOff
- The registry, the image name or the credentials
RESTARTS column
- CrashLoopBackOff
- Climbs with every attempt
- ImagePullBackOff
- Stays at 0
Application logs
- CrashLoopBackOff
- Yes: kubectl logs --previous
- ImagePullBackOff
- None. The app never ran
Where to look
- CrashLoopBackOff
- Exit code under Last State, then the previous logs
- ImagePullBackOff
- The Events in kubectl describe pod: the pull error message
Typical fix
- CrashLoopBackOff
- Fix the config, command or dependency the app needs
- ImagePullBackOff
- Fix the image tag, add imagePullSecrets, or wait out a rate limit
In short
CrashLoopBackOff vs ImagePullBackOff: the difference
CrashLoopBackOff: the container starts and then exits. ImagePullBackOff: the image never arrives, so the container never starts.
Both statuses are the kubelet waiting before another attempt, with the wait growing each time up to five minutes. What it is retrying is different. With CrashLoopBackOff the image was pulled and the container did start; the process inside then exited, so there are logs from the failed run and an exit code to read. The fault is in the application or its configuration. With ImagePullBackOff the kubelet never got as far as starting anything, because the container runtime could not fetch the image: the tag does not exist, the registry needs credentials the pod does not have, the registry is rate limiting, or the image was built for another CPU architecture. There are no application logs, because the application never ran. The quickest way to tell them apart is the restart count: it climbs in a crash loop and stays at zero while an image cannot be pulled.
Your turn
Which one is this?
Which one is this? A new pod has been at 0/1 for ten minutes. RESTARTS is 0, kubectl logs returns an error saying the container is waiting to start, and the events mention “manifest unknown”.
Related errors
Questions
- What is the difference between CrashLoopBackOff and ImagePullBackOff?
- In a crash loop the container starts and then exits, so the kubelet keeps restarting it. With ImagePullBackOff the image cannot be downloaded, so the container never starts at all.
- Why are there no logs for a pod in ImagePullBackOff?
- Because the application never ran. Logs come from a running container, and without the image there is none. The reason is in the pod's events instead.
- Do both back-offs work the same way?
- Broadly yes. In both cases the kubelet waits longer after each failed attempt, up to five minutes by default, and keeps trying until the cause is fixed.
Sources: Kubernetes docs: Images, including ImagePullBackOff ↗ · Kubernetes docs: Pod lifecycle, container restart policy ↗ · Report a problem
Diagrams are our own simulations. All wording is original and paraphrases the linked Kubernetes documentation.
Practise: diagnose the cluster
Read the terminal, watch the animation, pick the error and the first fix.