Kubernetes Troubleshooting

Kubernetes CrashLoopBackOff

Learn what CrashLoopBackOff means, how to identify the root cause, which kubectl commands to use, and how to troubleshoot a container that repeatedly starts and crashes.

What is CrashLoopBackOff?

CrashLoopBackOff means Kubernetes has detected that a container is repeatedly starting and then terminating. Kubernetes restarts the container, but after repeated failures it waits progressively longer between restart attempts.

The important point is that CrashLoopBackOff is usually a symptom, not the root cause. The application inside the container is often failing for another reason.

Step 1: Check the Pod Status

Start by checking the pods in the namespace.

kubectl get pods

You may see something similar to:

NAME                         READY   STATUS             RESTARTS
my-app-7d8f9c6b7d-abc12     0/1     CrashLoopBackOff   5

The RESTARTS column is especially useful. Repeated restarts indicate that the container is not staying alive.

Step 2: Check the Pod Description

kubectl describe pod <pod-name>

Look at the State, Last State, Exit Code, and Events sections.

Step 3: Check Container Logs

Application logs are often the fastest way to identify why the container is exiting.

kubectl logs <pod-name>

Check the Previous Container

If the container crashes too quickly, inspect the logs from the previous container instance:

kubectl logs <pod-name> --previous

This command is particularly important when troubleshooting CrashLoopBackOff.

Common Causes of CrashLoopBackOff

Application Crash

The application starts and then exits because of an application error, invalid configuration, missing dependency, or runtime exception.

Incorrect Configuration

Environment variables, ConfigMaps, Secrets, command arguments, or configuration files may contain incorrect values.

Failed Health Checks

Incorrect liveness or startup probes can cause Kubernetes to restart an otherwise running container.

Missing Environment Variables

The application may require variables that were not provided through the Deployment, ConfigMap, or Secret.

Incorrect Container Command

The image may start with a command or argument that does not exist or causes the application to exit immediately.

Resource Problems

Memory limits, CPU limits, or other resource constraints can cause containers to terminate unexpectedly.

Useful kubectl Commands

Check Pod Status

kubectl get pods

Start by checking the pod status and restart count. A high restart count is a common sign that the container is repeatedly failing.

Check Pod Details

kubectl describe pod <pod-name>

Shows container state, restart information, events, probes, image details, mounts, and scheduling information.

Check Current Logs

kubectl logs <pod-name>

Displays logs from the currently running container instance or the most recent container output.

Check Previous Container Logs

kubectl logs <pod-name> --previous

Very useful for CrashLoopBackOff because the previous container may have crashed before you could inspect its logs.

Check Events

kubectl get events --sort-by=.lastTimestamp

Shows recent Kubernetes events, which can reveal image, scheduling, probe, mount, or resource-related problems.

Check Pod in a Namespace

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

Use the namespace option when the affected pod is not running in the default namespace.

Check Kubernetes Events

Events can reveal problems that are not obvious from the application logs.

kubectl get events --sort-by=.lastTimestamp

You can also inspect events for a specific pod with:

kubectl describe pod <pod-name>

Common Fixes

✓Check the application logs before changing the Deployment.
✓Use kubectl logs --previous when the container has already restarted.
✓Inspect pod events with kubectl describe pod.
✓Verify environment variables, ConfigMaps, and Secrets.
✓Check liveness and startup probe configuration.
✓Verify the container image and its startup command.
✓Check whether the container was terminated because of memory pressure.
✓Confirm that required files, volumes, and mounts are available.

Example Troubleshooting Flow

1. Find the pod
```
kubectl get pods
```
2. Inspect the pod
```
kubectl describe pod <pod-name>
```
3. Check current logs
```
kubectl logs <pod-name>
```
4. Check logs from the previous crash
```
kubectl logs <pod-name> --previous
```

5. Check events

kubectl get events --sort-by=.lastTimestamp

6. Fix the underlying application or configuration issue

Quick CrashLoopBackOff Checklist

✓ Check pod status and restart count.
✓ Run kubectl describe pod.
✓ Check current container logs.
✓ Check kubectl logs --previous.
✓ Inspect Kubernetes events.
✓ Verify ConfigMaps and Secrets.
✓ Check startup and liveness probes.
✓ Check container command and arguments.
✓ Check resource limits and termination reasons.