Kubernetes Pod Troubleshooting

First Steps

When a pod is not running, start here:

# What state is it in?
kubectl get pods

# Why?
kubectl describe pod <pod-name>

# What did the app say?
kubectl logs <pod-name>

# Previous crash logs
kubectl logs <pod-name> --previous

CrashLoopBackOff

The container starts, crashes, and Kubernetes keeps restarting it.

Check logs:

kubectl logs <pod-name> --previous

Common causes: - Application error (check stack trace in logs) - Missing environment variable or config - Wrong command or entrypoint

Quick debug — run a shell instead:

kubectl run debug --image=<your-image> --rm -it -- /bin/sh

ImagePullBackOff

Kubernetes cannot pull the container image.

kubectl describe pod <pod-name> | grep -A5 "Events"

Fixes: - Wrong image name: check for typos in the deployment spec - Private registry: create an image pull secret

kubectl create secret docker-registry regcred \
  --docker-server=ghcr.io \
  --docker-username=<user> \
  --docker-password=<token>

Add to your pod spec:

spec:
  imagePullSecrets:
    - name: regcred

Pending Pod

Pod stays in Pending state — not scheduled to any node.

kubectl describe pod <pod-name> | grep -A10 "Events"

Common causes: - Insufficient resources: no node has enough CPU/memory

kubectl describe nodes | grep -A5 "Allocated resources"

• Node selector or affinity mismatch: pod requires a label no node has
• PVC not bound: the persistent volume claim is waiting

kubectl get pvc

OOMKilled

Container exceeded its memory limit and was killed.

kubectl describe pod <pod-name> | grep -i "oom\|killed\|memory"

Fix: increase the memory limit or fix the memory leak:

resources:
  requests:
    memory: "256Mi"
  limits:
    memory: "512Mi"

Check actual usage:

kubectl top pod <pod-name>

Container Won't Start

Exit code 0 but pod keeps restarting — the process exits immediately.

Common fix: your container needs a foreground process. Docker images that work with docker run may exit in Kubernetes because there is no TTY.

# Wrong — exits immediately
command: ["bash", "-c", "echo hello"]

# Right — stays running
command: ["bash", "-c", "echo hello && sleep infinity"]

Network Issues

Pod is running but cannot be reached:

# Check service endpoints
kubectl get endpoints <service-name>

# Test from inside the cluster
kubectl run curl --image=curlimages/curl --rm -it -- curl http://<service-name>:<port>

# Check DNS
kubectl run dns --image=busybox --rm -it -- nslookup <service-name>

Quick Reference

Related Posts

- Local Kubernetes with Kind for local testing - Monitoring ML Models in K8s for observability - CI/CD for ML on Kubernetes for deployment pipelines -e ---

Ready to go deeper? Explore our hands-on DevOps courses — from Docker and Terraform to MLflow on Kubernetes.