How to Fix Docker Container CrashLoopBackOff – Step‑by‑Step Guide for 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

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

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

b) Pull container logs

kubectl logs my-app -c my-app

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"]

Fix:

CMD ["python", "app.py"]

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://...

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

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"

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:

• Download the pre‑configured script here
• Get the complete patch tool
• Access the full repository fix Copy the script into your image, rebuild, and redeploy.

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

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.