Common Kubernetes Problems and How to Troubleshoot Them

Kubernetes troubleshooting follows a pattern: observe the symptom, check the relevant objects, read the events and logs, and apply a fix. Here are the most common problems and their solutions.

CrashLoopBackOff

A pod in CrashLoopBackOff status is starting, crashing, and restarting repeatedly.

Diagnosis: kubectl describe pod pod-name (check Events section) kubectl logs pod-name (check application logs) kubectl logs pod-name --previous (check logs from the crashed instance)

Common causes: - Application error (missing configuration, database connection failure) - Incorrect command or entrypoint in the container spec - Missing environment variables or secrets - OOMKill (memory limit exceeded)

Fix the root cause and Kubernetes will restart the pod successfully.

Pending Pods

A Pending pod cannot be scheduled to any node.

Diagnosis: kubectl describe pod pod-name (check Events for scheduling failures)

Common causes: - Insufficient resources: no node has enough CPU or memory for the pod's requests - Node taints: the pod does not tolerate the taints on available nodes - Node selector or affinity: the pod's node selector does not match any nodes - PVC binding failure: the requested PersistentVolumeClaim cannot be bound

Solutions: reduce resource requests, add nodes, adjust taints/tolerations, or fix PVC configuration.

ImagePullBackOff

The container runtime cannot pull the specified container image.

Common causes: - Typo in the image name or tag - Private registry authentication not configured - Registry is unreachable (network issue) - Image does not exist in the specified registry

Verify the image name, check imagePullSecrets, and test registry connectivity.

Service Connectivity Issues

Pods cannot connect to a Service.

Diagnosis: kubectl get endpoints service-name (verify endpoints exist) kubectl exec pod-name -- nslookup service-name (test DNS) kubectl exec pod-name -- curl http://service-name:port (test HTTP)

Common causes: - Service selector does not match any pod labels - Pods are not ready (readiness probe failing) - Network policy blocking traffic - Port mismatch between Service and container

Resource Exhaustion

Pods are being OOMKilled or CPU-throttled.

Diagnosis: kubectl top pods (check actual resource usage) kubectl describe pod pod-name (check for OOMKilled events)

Solution: increase memory limits (for OOMKilled), increase CPU limits (for throttling), or optimize application resource usage.

DNS Issues

Pods cannot resolve service names.

Diagnosis: kubectl exec pod-name -- nslookup kubernetes.default (test core DNS) kubectl get pods -n kube-system -l k8s-app=kube-dns (check CoreDNS health)

Common causes: - CoreDNS pods are not running - Network policy blocking DNS traffic (port 53) - Custom DNS configuration overriding cluster DNS

General Troubleshooting Workflow

1. Check pod status: kubectl get pods 2. Describe the pod: kubectl describe pod pod-name 3. Read logs: kubectl logs pod-name 4. Check events: kubectl get events --sort-by=.lastTimestamp 5. Verify related objects (Services, PVCs, ConfigMaps, Secrets) 6. Test network connectivity between components

Most Kubernetes problems can be diagnosed with these steps.

Key Takeaways

• Start every diagnosis with `kubectl describe pod` and `kubectl logs` — events and application logs reveal the root cause in most cases
• CrashLoopBackOff almost always points to an application error, missing configuration, or OOMKill — check `--previous` logs for the real failure message
• Pending pods indicate scheduling failures: insufficient resources, unsatisfied taints/tolerations, or unbound PVCs are the most common causes
• Service connectivity problems usually trace back to label mismatches, failing readiness probes, or missing Network Policy allow rules
• A consistent workflow (status → describe → logs → events → related objects → connectivity) resolves most Kubernetes issues systematically