EC
CrashLoopBackOff
DockerERRORNotableRuntimeHIGH confidence

Container is starting and crashing in a loop

What this means

While not a Docker error directly, CrashLoopBackOff is a critical status reported by container orchestrators like Kubernetes. It means a container starts, immediately crashes, and Kubernetes keeps trying to restart it, only for it to crash again in a loop, with an increasing back-off delay.

Why it happens
  1. 1An application error on startup, such as a misconfigured database connection string.
  2. 2An invalid command or arguments in the Dockerfile's CMD or ENTRYPOINT.
  3. 3Missing configuration files or volumes that the application expects to be present.
  4. 4The application exiting immediately after starting because it has no long-running task to perform (e.g., a script that finishes).
How to reproduce

A Node.js application is configured to connect to 'mongodb://localhost:27017' but no MongoDB container is running in the same pod.

trigger — this will error
trigger — this will error
# Check the status of pods in a Kubernetes namespace
kubectl get pods -n my-namespace

# Describe the failing pod to see container statuses and events
kubectl describe pod my-app-pod-xyz -n my-namespace

expected output

NAME                      READY   STATUS             RESTARTS   AGE
my-app-pod-xyz-6d...    0/1     CrashLoopBackOff   5          10m

Fix 1

Check Container Logs

WHEN This is the first and most important step to diagnose the issue.

Check Container Logs
# Get logs from the failing container
kubectl logs my-app-pod-xyz -n my-namespace

# If it restarted, get logs from the previous instance
kubectl logs my-app-pod-xyz -n my-namespace --previous

Why this works

The application's logs will almost always contain the specific error message (e.g., 'Connection refused', 'File not found') that explains why it is crashing.

Fix 2

Inspect Pod Events

WHEN The logs are empty or unhelpful; the issue might be at the orchestrator level.

Inspect Pod Events
kubectl describe pod my-app-pod-xyz -n my-namespace

Why this works

The 'Events' section of the output can reveal problems that happen before the container even starts, such as failures to mount a volume or pull an image.

What not to do

✕ Delete the pod immediately.

Deleting the pod also deletes its logs and events, which are the primary sources of information for debugging the crash. Always check logs first.

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Docker errors