How to Fix Docker CrashLoopBackOff in Kubernetes – Step‑by‑Step Troubleshooting Guide

Introduction

The CrashLoopBackOff status is one of the most common errors you’ll see when running Docker containers in a Kubernetes cluster. It indicates that a container starts, crashes, and Kubernetes keeps trying to restart it. This guide walks you through the root causes and provides concrete, reproducible steps to get your pod back to a healthy state.

Quick Checklist

1. Inspect pod status – kubectl get pod.
2. Read events – kubectl describe pod.
3. Check logs – kubectl logs (use --previous for the last run).
4. Validate probes – readiness/liveness definitions.
5. Review resource limits – OOMKill often triggers crashes.

Step‑by‑Step Diagnosis

1. Inspect the pod

kubectl get pod my-app -n prod
kubectl describe pod my-app -n prod

The describe output shows events such as BackOff timestamps, OOMKilled messages, or failed health checks.

2. View container logs

# Current logs
kubectl logs my-app -n prod
# Logs from the previous container instance (useful after a crash)
kubectl logs my-app -n prod --previous

Look for stack traces, missing configuration files, or permission errors.

3. Check readiness and liveness probes

Incorrect probe settings are a frequent culprit. Example probe definition:

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5
readinessProbe:
  exec:
    command: ["cat", "/tmp/ready"]
  initialDelaySeconds: 5
  periodSeconds: 3

If the probe fails too early, the container will be killed before it can start properly. Adjust initialDelaySeconds or the command itself.

4. Verify resource requests & limits

resources:
  requests:
    cpu: "250m"
    memory: "128Mi"
  limits:
    cpu: "500m"
    memory: "256Mi"

If the container exceeds its memory limit, the kernel will OOM‑kill it, causing a CrashLoopBackOff.

5. Re‑create the pod with a minimal manifest

Create a temporary pod that runs sleep 3600 using the same image:

apiVersion: v1
kind: Pod
metadata:
  name: debug-pod
spec:
  containers:
  - name: debug
    image: your-registry/your-image:tag
    command: ["/bin/sh", "-c", "sleep 3600"]
    resources:
      limits:
        memory: "256Mi"

If this pod stays running, the problem is likely inside your application code rather than the environment.

Common Causes & Fixes

Cause	Fix
Missing env var	Add the variable to the Deployment or ConfigMap.
Bad start command	Correct command/args in the container spec.
Failed DB connection	Ensure the service name, port, and credentials are correct; use initContainers to wait for the DB.
File permission errors	Adjust securityContext.runAsUser or volume fsGroup.
OOMKill	Increase memory limits or optimise memory usage.

Automated Fix

You can download a ready‑to‑use script that applies the most frequent fixes for CrashLoopBackOff issues:
Download the pre-configured script here

Alternatively, get the complete patch tool:
Get the complete patch tool

Access the full repository fix:
Access the full repository fix

Conclusion

CrashLoopBackOff is rarely a mystery; it’s almost always a misconfiguration or a missing dependency. By following the systematic steps above—inspecting the pod, reading logs, validating probes, and tuning resources—you can pinpoint the root cause quickly. Keep the checklist handy, and when in doubt, use the provided script to automate the most common remediation steps.