Kubernetes Exit Codes Explained: How to Diagnose and Fix Failing Containers
You deploy your containerized application in Kubernetes, but then the pod has crashed unexpectedly. You check the logs and see an exit code, but what does it actually mean? Is it an application bug? A resource issue? Or something else?
If you’ve ever been stuck troubleshooting a failing container, understanding exit codes is key to diagnosing and resolving the issue quickly. These codes tell you why a container stopped running, whether it was a planned shutdown, an error, or a system-level termination.
In this guide, you’ll learn:
What Kubernetes container exit codes mean
How to troubleshoot the most common exit codes
Practical steps to fix and prevent container failures
By the end, you’ll be able to decode exit statuses like a pro, saving time and frustration when debugging Kubernetes workloads. Let’s dive in!
What Are Exit Codes in Kubernetes?
When a container stops running in Kubernetes, it returns an exit code that explains why it terminated. Exit codes come from the Linux operating system and are used by container runtimes like Docker and containerd.
Kubernetes uses these exit codes to report the reason a container stopped, helping you troubleshoot and fix issues faster.
Common Kubernetes Exit Codes and Their Meanings
First of all, Exit codes are defined by the OS and architecture. Kubernetes lays no claim on any particular code, but we can have a general guideline like the following table to help you debug most of the problems.
Below is a breakdown of the most frequently encountered exit codes when working with Kubernetes containers:
Troubleshooting Exit Codes: Practical Solutions
Here’s how to diagnose and fix common container exit codes:
Exit Code 1 (Application Error)
What to check:
Review application logs (kubectl logs <pod-name>)
Ensure environment variables and dependencies are correctly set
Test the container locally (docker run <image-name>)
How to fix it:
Update application code to handle exceptions properly
Check for missing dependencies in the container image
Verify that the correct image version is used in the deployment
Exit Code 125 (Container Failed to Run Error)
What to check:
Run kubectl describe pod <pod-name> to check for deployment issues
Look for permission errors in logs
check both the image and machine architecture and see if they match
How to fix it:
Ensure the container image is valid and exists (docker images)
Check if the Kubernetes node has sufficient resources
Exit Code 126 (Command Invoke Error)
What to check:
Verify that the command inside the container is executable (chmod +x <file>)
Check file permissions (ls -l)
run the container locally first, check if you can do the same as the pod is doing on startup
How to fix it:
Ensure commands have the correct execution permissions
Use the correct user permissions inside the container
Exit Code 137 (Immediate Termination — SIGKILL)
What to check:
Check if the container is hitting memory limits (kubectl describe pod <pod-name>)
Look for OOMKilled (Out of Memory Killed) in Kubernetes events
How to fix it:
Increase the memory limit in the container spec:
resources:
limits:
memory: "512Mi"Optimize the application to use less memory
Exit Code 139 (Segmentation Fault — SIGSEGV)
What to check:
Review application code for memory access violations
coding errors
Test application behavior in a local development environment
How to fix it:
Debug memory-related issues with tools like gdb
Fix invalid pointer dereferences in the code
Exit Code 143 (Graceful Termination — SIGTERM)
What to check:
Identify if Kubernetes is scaling down the pod
Look if kubernetes is setting the pod to terminating status
Preventing Container Failures: Best Practices
1️⃣ Use Resource Limits and Requests
- Prevent OOMKills (Exit Code 137) by setting resource limits.
resources:
requests:
memory: "256Mi"
limits:
memory: "512Mi"2️⃣ Monitor Logs and Events
- Use kubectl logs and kubectl describe pod to diagnose issues.
- Implement logging and monitoring tools (e.g., Prometheus, Grafana).
3️⃣ Handle Application Errors Gracefully
- Ensure the application handles exceptions to prevent Exit Code 1 errors.
- Use health checks (
livenessProbe,readinessProbe) in Kubernetes.
4️⃣ Test Containers Locally
- Run
docker run <image>before deploying to Kubernetes to catch issues early.
5️⃣ Implement Proper Shutdown Handling
- Trap SIGTERM signals and perform necessary cleanup before exit.
Conclusion
Understanding Kubernetes container exit codes can save you hours of debugging. Each exit code tells a story about why a container stopped — whether due to an application crash, resource issue, or system-level termination.
Next time your container fails, check the exit code first — it might just tell you exactly what went wrong!
Want more insights on DevOps, security, and automation?
Don’t miss out — Follow me!
Connect with me on Linkedin!
