How to troubleshoot Kubernetes CrashLoopBackOff

A CrashLoopBackOff status means Kubernetes has started a container, watched it exit, and is delaying the next restart so the same failure does not hammer the node. Troubleshooting starts by tying the visible pod status to the container's last termination state, logs, and workload events before changing the manifest.

The pod phase alone rarely names the root cause. kubectl describe pod shows the waiting reason, previous termination reason, exit code, restart count, owning controller, and event trail; kubectl logs with --previous often captures output from the short-lived container attempt that exited before the next restart.

A narrow fix starts only after the failing signal is clear. Use the namespace and pod name from the affected workload, confirm the exact container when the pod has more than one container, and change the owning Deployment, Job, StatefulSet, or manifest so the replacement pod is created from corrected state.

1. List the affected namespace and find the pod in CrashLoopBackOff.

   $ kubectl get pods -n app-prod
   NAME                   READY   STATUS             RESTARTS     AGE
   web-5f45f8d54f-xh9g5   0/1     CrashLoopBackOff   1 (3s ago)   11s

2. Describe the failing pod and read the container state, previous termination, exit code, restart count, and events.

   $ kubectl describe pod -n app-prod web-5f45f8d54f-xh9g5
   Name:             web-5f45f8d54f-xh9g5
   Namespace:        app-prod
   Controlled By:    ReplicaSet/web-5f45f8d54f
   ##### snipped #####
   Containers:
     busybox:
       State:          Waiting
         Reason:       CrashLoopBackOff
       Last State:     Terminated
         Reason:       Error
         Exit Code:    1
       Ready:          False
       Restart Count:  1
       Environment:    <none>
   ##### snipped #####
   Events:
     Type     Reason   Age              From     Message
     ----     ------   ----             ----     -------
     Warning  BackOff  1s (x2 over 2s)  kubelet  Back-off restarting failed container busybox in pod web-5f45f8d54f-xh9g5_app-prod

   The Controlled By line tells which controller created the pod. For a Deployment, apply the fix to the Deployment or its source manifest instead of editing the generated pod.

3. Read the previous container logs before the next restart hides the shortest failure output.

   $ kubectl logs -n app-prod pod/web-5f45f8d54f-xh9g5 --previous
   APP_CONFIG_PATH is required

   For multi-container pods, add -c with the container name shown under Containers in the describe output.
   Related: How to view Kubernetes pod logs

4. Check warning events for the same pod.

   $ kubectl events -n app-prod --for pod/web-5f45f8d54f-xh9g5 --types=Warning
   LAST SEEN         TYPE      REASON    OBJECT                     MESSAGE
   1s (x2 over 2s)   Warning   BackOff   Pod/web-5f45f8d54f-xh9g5   Back-off restarting failed container busybox in pod web-5f45f8d54f-xh9g5_app-prod

   Related: How to check Kubernetes events
   Tool: Kubernetes Events Timeline Analyzer

5. Apply the focused fix to the owning workload.

   $ kubectl set env deployment/web -n app-prod APP_CONFIG_PATH=/etc/web/config.yaml
   deployment.apps/web env updated

   The previous logs show a missing environment variable in this case. For probe failures, image startup errors, OOMKilled exits, or missing mounted files, change the specific field named by the logs, status, or events.

6. Watch the owning Deployment create a replacement pod.

   $ kubectl rollout status deployment/web -n app-prod
   deployment "web" successfully rolled out

7. Confirm that the replacement pod is running without restarts.

   $ kubectl get pods -n app-prod -l app=web
   NAME                   READY   STATUS    RESTARTS   AGE
   web-56fd96f647-2gfnz   1/1     Running   0          29s

8. Read the corrected workload logs to confirm the container reached its startup path.

   $ kubectl logs -n app-prod deployment/web
   configuration loaded from /etc/web/config.yaml