DEV Community

Deep Fix
Deep Fix

Posted on

Docker CrashLoopBackOff Fix: Step‑By‑Step Guide to Resolve Container Crashes

#docker #kubernetes #troubleshooting #devops

Docker CrashLoopBackOff Fix: Step‑By‑Step Guide to Resolve Container Crashes

When a pod repeatedly restarts with the CrashLoopBackOff status, it can stall a CI/CD pipeline and frustrate developers. This article walks you through the most common root causes and provides a clear, actionable troubleshooting workflow.

Understanding CrashLoopBackOff

CrashLoopBackOff is a Kubernetes pod phase that indicates the container started, crashed, and Kubernetes is backing off before trying again. It differs from a plain Error because the system respects the restart policy and adds exponential back‑off delays.

Common Causes

  1. Application entry‑point errors – missing env vars, bad config files, or syntax errors.
  2. Resource constraints – out‑of‑memory (OOMKilled) or CPU throttling.
  3. Incorrect health probes – liveness/readiness probes failing immediately.
  4. Image issues – corrupted layers or mismatched architecture.
  5. Dependency failures – database or external service not reachable.

Step‑by‑Step Debugging Checklist 

# 1. Identify the problematic pod
kubectl get pods -n <namespace>

# 2. Describe the pod to see events & recent restarts
kubectl describe pod <pod-name> -n <namespace>

# 3. Pull the latest logs (include previous container instance)
kubectl logs <pod-name> -n <namespace> --previous

# 4. If logs are empty, exec into the container (if it stays up long enough)
kubectl exec -it <pod-name> -n <namespace> -- /bin/sh
Enter fullscreen mode Exit fullscreen mode

1. Check Exit Code & Reason

The kubectl describe output often contains a line like:

State:          Running
Last State:     Terminated
  Reason:       Error
  Exit Code:    1
Enter fullscreen mode Exit fullscreen mode

An exit code of 1 usually means the application failed to start; 137 signals an OOM kill.

2. Validate Environment & ConfigMaps 

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  DATABASE_URL: "postgres://user:pass@db:5432/app"
Enter fullscreen mode Exit fullscreen mode

Make sure the pod mounts the ConfigMap correctly:

kubectl exec <pod-name> -- printenv | grep DATABASE_URL
Enter fullscreen mode Exit fullscreen mode

3. Inspect Health Probes

A too‑strict liveness probe can kill a container before it finishes initialization.

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 5   # increase this if startup takes longer
  periodSeconds: 10
Enter fullscreen mode Exit fullscreen mode

Adjust initialDelaySeconds or temporarily disable the probe to confirm.

4. Resource Limits

If the pod is OOM‑killed, increase its memory request/limit:

resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"
Enter fullscreen mode Exit fullscreen mode

Quick Fix Scripts

For repetitive issues you can drop a ready‑made patch into your CI pipeline. Download the pre‑configured script here to automatically adjust liveness probes and resource limits based on pod annotations.

If you need a more comprehensive solution, Get the complete patch tool which scans all pods in a namespace and generates a Helm values file.

For full source code and documentation, Access the full repository fix.

Preventive Best Practices

  • Define explicit resource requests/limits for every container.
  • Use restartPolicy: OnFailure only when you truly expect occasional crashes.
  • Version your ConfigMaps/Secrets and roll them out with rolling updates.
  • Monitor pod events with Prometheus alerts on kube_pod_container_status_waiting_reason{reason="CrashLoopBackOff"}.

By following this systematic approach, you can quickly pinpoint why a container is entering CrashLoopBackOff and apply a lasting fix. Happy debugging!

Top comments (0)