Kubernetes CrashLoopBackOff Error Fix

In this tutorial, you'll learn about Kubernetes CrashLoopBackOff Error Fix. We cover key concepts, practical examples, and best practices.

The Problem

Your pod restarts repeatedly and shows CrashLoopBackOff:

NAME                     READY   STATUS             RESTARTS   AGE
my-app-6b4c9f8d7-xyz99   0/1     CrashLoopBackOff   5          3m

The container starts, crashes, Kubernetes restarts it, and it crashes again. This loop means the application process inside the container exits with a non-zero code immediately or within a few seconds of starting.

Quick Fix

Step 1: Read the logs

kubectl logs my-app-6b4c9f8d7-xyz99

If the pod has restarted, use the previous instance's logs:

kubectl logs my-app-6b4c9f8d7-xyz99 --previous

The log output usually shows the exact error -- a missing file, a failed database connection, or a misconfigured environment variable.

Step 2: Check the exit code

kubectl get pod my-app-6b4c9f8d7-xyz99 -o jsonpath='{.status.containerStatuses[0].state.terminated.exitCode}'

Common exit codes:

• 1 -- General application error (missing dependency, bad config)
• 137 -- Killed by SIGKILL (OOM, resource limit)
• 139 -- Segmentation fault (memory corruption, null pointer)
• 143 -- Killed by SIGTERM (graceful shutdown failed)

Step 3: Debug with a shell

Override the entrypoint to keep the container alive:

kubectl run debug --image=my-image -it --rm --restart=Never -- sh

Once inside, manually start your application to see the error in real time:

/app/start.sh
# Error output appears immediately

Step 4: Fix environment variables and configmaps

Missing environment variables are a common cause. Compare your deployment spec to what the application expects:

WRONG -- missing required env var:

env:
- name: DB_HOST
  value: "localhost"  # wrong -- should be service name
# Missing DB_PASSWORD entirely

RIGHT -- use ConfigMap and Secret:

env:
- name: DB_HOST
  valueFrom:
    configMapKeyRef:
      name: app-config
      key: db_host
- name: DB_PASSWORD
  valueFrom:
    secretKeyRef:
      name: app-secret
      key: db_password

Step 5: Check liveness and readiness probes

A failing liveness probe causes restarts after the container is running:

kubectl describe pod my-app-6b4c9f8d7-xyz99

Liveness probe failed: HTTP probe failed with statuscode: 503

WRONG -- probe path does not exist:

livenessProbe:
  httpGet:
    path: /healthz   # application has no /healthz endpoint
    port: 8080

RIGHT -- use an endpoint that exists:

livenessProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 5

Step 6: Increase startup time for slow applications

If your app starts slowly, the probes kill it before it is ready:

startupProbe:
  httpGet:
    path: /health
    port: 8080
  initialDelaySeconds: 30
  periodSeconds: 10
  failureThreshold: 12

Use DodaTech's K8s Debugger to visualize probe timing and identify mismatches between startup time and probe configuration.

Prevention

• Always test your container image locally with docker run before deploying.
• Add a health endpoint (/health or /readyz) to every service.
• Use startupProbe for applications with long initialization.
• Set terminationGracePeriodSeconds long enough for cleanup.
• Store configuration in ConfigMaps, not hardcoded in the image.

Common Mistakes with crashloopbackoff

1. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
2. Using return to exit a function early instead of wrapping a pure value in the monad
3. Mixing let bindings with <- bindings in do notation, producing type errors

These mistakes appear frequently in real-world K8S code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ