DEV Community

Deep Fix
Deep Fix

Posted on

How to Fix Docker Container CrashLoopBackOff – Step‑by‑Step Guide for DevOps

#docker #kubernetes #troubleshooting #devops

Introduction

If you’ve ever seen a pod stuck in CrashLoopBackOff, you know the frustration. This guide walks you through the most common causes, how to diagnose them, and concrete fixes you can apply today.

Quick Checklist

  1. Inspect pod events: kubectl describe pod <name>
  2. View container logs: kubectl logs <pod> -c <container>
  3. Check Dockerfile / entrypoint scripts.
  4. Verify resource limits and health probes.
  5. Re‑deploy with corrected configuration.

1. Understanding CrashLoopBackOff

CrashLoopBackOff means the container started, crashed, and Kubernetes is backing off before trying again. The root cause is usually:

  • Runtime errors (missing binary, permission issues)
  • Mis‑configured command/args
  • Failing liveness/readiness probes
  • Exhausted resources (OOMKilled)

2. Diagnose the Problem

a) Gather pod details 

kubectl get pod my-app -o wide
kubectl describe pod my-app
Enter fullscreen mode Exit fullscreen mode

Look for the State, Reason, and Message fields. Example output:

State:          Waiting
Reason:         CrashLoopBackOff
Message:        Back-off 5s restarting failed container=my-app
Enter fullscreen mode Exit fullscreen mode

b) Pull container logs 

kubectl logs my-app -c my-app
Enter fullscreen mode Exit fullscreen mode

If the container exits immediately, the logs often contain the stack trace or permission denied errors.

3. Common Fixes

3.1 Incorrect Entrypoint or CMD

A typical Dockerfile mistake:

FROM python:3.10-slim
COPY . /app
WORKDIR /app
# Wrong: missing "python" interpreter
CMD ["app.py"]
Enter fullscreen mode Exit fullscreen mode

Fix:

CMD ["python", "app.py"]
Enter fullscreen mode Exit fullscreen mode

Redeploy the image and the pod should start normally.

3.2 Missing Environment Variables

If your app expects DATABASE_URL:

kubectl set env deployment/my-app DATABASE_URL=postgres://...
Enter fullscreen mode Exit fullscreen mode

Or add it to the manifest under env:.

3.3 Failing Health Probes

A liveness probe that times out will kill the container:

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 5
  periodSeconds: 10
Enter fullscreen mode Exit fullscreen mode

Increase initialDelaySeconds or verify the endpoint returns 200.

3.4 Resource Limits

OOMKilled shows up as Reason: OOMKilled. Raise limits:

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

4. Applying a Quick Patch

Sometimes you need to inject a small script into the running container to debug further. You can download a ready‑made patch tool:

5. Full Example – From Broken to Healthy 

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-app
  template:
    metadata:
      labels:
        app: my-app
    spec:
      containers:
      - name: my-app
        image: myregistry/my-app:latest
        command: ["python", "app.py"]
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef:
              name: db-secret
              key: url
        resources:
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 15
          periodSeconds: 20
Enter fullscreen mode Exit fullscreen mode

Deploy with kubectl apply -f deployment.yaml and watch the pod transition to Running.

Conclusion

CrashLoopBackOff is rarely a mystery; it’s a symptom of a mis‑configuration or runtime error. By systematically checking events, logs, probes, and resources, you can pinpoint the issue in minutes. Keep this guide handy, and remember the quick‑patch script link above for on‑the‑fly debugging.

Top comments (0)