DEV Community

Deep Fix
Deep Fix

Posted on

How to Resolve Docker Container CrashLoopBackOff in Kubernetes – Step-by-Step Guide

#docker #kubernetes #troubleshooting #devops

Introduction

If you work with containers on Kubernetes, the dreaded CrashLoopBackOff status is a common roadblock. This post walks you through the root causes, diagnostic commands, and concrete fixes so you can get your pod back to a steady Running state.

What is CrashLoopBackOff?

CrashLoopBackOff means the container started, crashed, and Kubernetes is repeatedly trying to restart it. The back‑off timer grows after each failure, so the pod never reaches Ready.

Common Root Causes

  • Faulty ENTRYPOINT or CMD in the Docker image
  • Missing or incorrect environment variables
  • Unhealthy liveness/readiness probes
  • Resource limits that cause OOM kills
  • Dependency services not reachable at start‑up

Step‑by‑Step Troubleshooting

  1. Inspect pod status 
   kubectl get pod myapp-pod -n myns
   kubectl describe pod myapp-pod -n myns
Enter fullscreen mode Exit fullscreen mode
  1. Check container logs 
   kubectl logs myapp-pod -c myapp -n myns
Enter fullscreen mode Exit fullscreen mode
  1. Validate the image entrypoint 
   FROM python:3.11-slim
   WORKDIR /app
   COPY . .
   # Common mistake: typo in the script name
   ENTRYPOINT ["python", "app.py"]
Enter fullscreen mode Exit fullscreen mode

If the script name is wrong, the container exits with code 127.

  1. Verify environment variables 
   env:
     - name: DATABASE_URL
       valueFrom:
         secretKeyRef:
           name: db-secret
           key: url
Enter fullscreen mode Exit fullscreen mode

Missing keys cause the application to abort immediately.

  1. Adjust liveness/readiness probes 
   livenessProbe:
     httpGet:
       path: /healthz
       port: 8080
     initialDelaySeconds: 5
     periodSeconds: 10
   readinessProbe:
     exec:
       command: ["cat", "/tmp/ready"]
     initialDelaySeconds: 2
     periodSeconds: 5
Enter fullscreen mode Exit fullscreen mode

Overly aggressive probes kill a still‑initializing container.

  1. Check resource limits 
   resources:
     limits:
       memory: "256Mi"
       cpu: "500m"
Enter fullscreen mode Exit fullscreen mode

If the app needs more memory, it will be OOM‑killed and restart.

  1. Redeploy after fixing 
   kubectl apply -f deployment.yaml
   kubectl rollout status deployment/myapp -n myns
Enter fullscreen mode Exit fullscreen mode

Example: Fixing an Entrypoint Typo

A pod kept crashing with the log exec: "nodejs": executable file not found in $PATH. The Dockerfile incorrectly used nodejs instead of node.

# Bad
ENTRYPOINT ["nodejs", "server.js"]

# Fixed
ENTRYPOINT ["node", "server.js"]
Enter fullscreen mode Exit fullscreen mode

After rebuilding and pushing the image, the pod transitioned to Running.

Monitoring After the Fix

  • kubectl get events -n myns --sort-by=.metadata.creationTimestamp
  • Use k9s or Lens to watch pod restarts in real time.
  • Set up alerts in Prometheus/Grafana for kube_pod_container_status_waiting_reason.

Resources

By following these steps, you can quickly pinpoint why a container enters CrashLoopBackOff and apply a lasting solution. Happy debugging!

Top comments (0)