--- title: "Common Kubernetes Issues and Troubleshooting" description: "Use this file as a symptom-to-fix lookup after collecting diagnostics." type: skill canonical_url: https://claudary.paisolsolutions.com/skills/common-issues-2 source: "Claudary" difficulty: intermediate author: "Claude Code Knowledge Pack" date: 2026-07-10T11:18:34.856Z license: CC-BY-4.0 attribution: "Common Kubernetes Issues and Troubleshooting — Claudary (https://claudary.paisolsolutions.com/skills/common-issues-2)" --- # Common Kubernetes Issues and Troubleshooting Use this file as a symptom-to-fix lookup after collecting diagnostics. ## Overview # Common Kubernetes Issues and Troubleshooting ## How to Use This Reference Use this file as a symptom-to-fix lookup after collecting diagnostics. Suggested sequence: 1. Match the observed symptom with the closest issue heading. 2. Run the listed `Debugging Steps` commands and confirm you can reproduce the failure. 3. Apply the least disruptive fix from `Solutions`. 4. Re-run verification commands and confirm the symptom is gone. If you need an end-to-end decision flow instead of a known symptom lookup, use `./references/troubleshooting_workflow.md`. ## Pod Issues ### CrashLoopBackOff **Symptoms:** - Pod repeatedly crashes and restarts - Status shows `CrashLoopBackOff` - Increasing restart count **Common Causes:** 1. Application error causing immediate exit 2. Missing environment variables or configuration 3. Insufficient resources (memory/CPU) 4. Failed health checks (liveness probe) 5. Missing dependencies or volumes **Debugging Steps:** ```bash # Check pod events kubectl describe pod -n # View current logs kubectl logs -n # View previous container logs (from crashed container) kubectl logs -n --previous # Check resource limits kubectl get pod -n -o yaml | grep -A 5 resources # Check liveness/readiness probes kubectl get pod -n -o yaml | grep -A 10 livenessProbe ``` **Solutions:** - Fix application code causing crashes - Add missing environment variables via ConfigMap/Secret - Increase resource limits - Adjust or remove overly aggressive liveness probes - Ensure all required volumes are mounted and accessible --- ### ImagePullBackOff / ErrImagePull **Symptoms:** - Pod status shows `ImagePullBackOff` or `ErrImagePull` - Pod fails to start - Events show image pull errors **Common Causes:** 1. Image doesn't exist or wrong image name/tag 2. Private registry requires authentication 3. Network issues accessing registry 4. Image pull secrets missing or incorrect 5. Registry rate limiting **Debugging Steps:** ```bash # Check exact error message kubectl describe pod -n # Verify image name and tag kubectl get pod -n -o yaml | grep image: # Check image pull secrets kubectl get pod -n -o yaml | grep imagePullSecrets -A 2 # List secrets in namespace kubectl get secrets -n # Test image pull manually on node docker pull ``` **Solutions:** - Verify image exists in registry: `docker pull ` - Create image pull secret: `kubectl create secret docker-registry --docker-server= --docker-username= --docker-password=` - Add imagePullSecrets to pod spec - Use correct image tag (avoid `latest` in production) - Check registry credentials and permissions --- ### Pending Pods **Symptoms:** - Pod stuck in `Pending` state - Pod never gets scheduled **Common Causes:** 1. Insufficient cluster resources (CPU/memory) 2. No nodes match pod's node selector 3. Taints on nodes prevent scheduling 4. PersistentVolumeClaim not bound 5. Pod affinity/anti-affinity rules cannot be satisfied **Debugging Steps:** ```bash # Check scheduling events kubectl describe pod -n # Check node resources kubectl top nodes kubectl describe nodes # Check PVC status kubectl get pvc -n # Check node selectors and taints kubectl get pod -n -o yaml | grep -A 5 nodeSelector kubectl get nodes -o custom-columns=NAME:.metadata.name,TAINTS:.spec.taints ``` **Solutions:** - Add more nodes to cluster or free up resources - Remove/adjust node selectors - Add tolerations for taints - Create or fix PersistentVolume for PVC - Adjust affinity/anti-affinity rules - Check resource quotas: `kubectl get resourcequota -n ` --- ### OOMKilled (Out of Memory) **Symptoms:** - Pod restarts with exit code 137 - Last state shows `OOMKilled` - Container was killed due to memory **Debugging Steps:** ```bash # Check pod status and last state kubectl get pod -n -o yaml | grep -A 10 lastState # Check memory limits kubectl get pod -n -o yaml | grep -A 5 resources # Check actual memory usage kubectl top pod -n --containers ``` **Solutions:** - Increase memory limits - Fix memory leaks in application - Optimize application memory usage - Add memory requests/limits if missing --- ## Service and Networking Issues ### Service Not Accessible **Symptoms:** - Cannot connect to service from within or outside cluster - Connection timeout or refused **Common Causes:** 1. Service selector doesn't match pod labels 2. Target port mismatch 3. Network policies blocking traffic 4. Service type incorrect (ClusterIP vs LoadBalancer) 5. Endpoints not created **Debugging Steps:** ```bash # Check service configuration kubectl get svc -n -o yaml # Check endpoints kubectl get endpoints -n # Check pod labels kubectl get pods -n --show-labels # Test from another pod kubectl run tmp-shell --rm -i --tty --image nicolaka/netshoot -- /bin/bash # Inside pod: curl ..svc.cluster.local # Check network policies kubectl get networkpolicies -n ``` **Solutions:** - Ensure service selector matches pod labels exactly - Verify port and targetPort are correct - Check network policies allow traffic - Use correct service type for use case - Ensure pods are running and ready --- ### DNS Resolution Failures **Symptoms:** - Pods cannot resolve service names - `nslookup` or `dig` commands fail - DNS timeouts **Common Causes:** 1. CoreDNS not running properly 2. DNS service not accessible 3. Pod DNS config incorrect 4. Network policies blocking DNS **Debugging Steps:** ```bash # Check CoreDNS pods kubectl get pods -n kube-system -l k8s-app=kube-dns # Check CoreDNS logs kubectl logs -n kube-system -l k8s-app=kube-dns # Test DNS from pod kubectl exec -n -- nslookup kubernetes.default # Check pod DNS config kubectl exec -n -- cat /etc/resolv.conf # Check DNS service kubectl get svc -n kube-system kube-dns ``` **Solutions:** - Restart CoreDNS: `kubectl rollout restart deployment/coredns -n kube-system` - Verify DNS service endpoints exist - Check network policies allow port 53 - Verify kubelet DNS settings --- ## Volume and Storage Issues ### PersistentVolumeClaim Pending **Symptoms:** - PVC stuck in `Pending` state - Pod cannot start due to volume mount **Debugging Steps:** ```bash # Check PVC status kubectl describe pvc -n # List available PVs kubectl get pv # Check storage class kubectl get storageclass ``` **Solutions:** - Create matching PersistentVolume - Verify storage class exists and is correct - Check volume provisioner is working - Ensure sufficient storage available --- ## Resource and Configuration Issues ### ConfigMap/Secret Not Found **Symptoms:** - Pod fails to start - Events show volume mount errors - Missing environment variables **Debugging Steps:** ```bash # List ConfigMaps kubectl get configmaps -n # List Secrets kubectl get secrets -n # Check pod configuration kubectl get pod -n -o yaml | grep -A 10 env ``` **Solutions:** - Create missing ConfigMap/Secret - Verify names match exactly (case-sensitive) - Check namespace matches - Ensure keys referenced exist in ConfigMap/Secret --- ## Performance Issues ### High CPU/Memory Usage **Debugging Steps:** ```bash # Check resource usage kubectl top nodes kubectl top pods -n # Check resource requests/limits kubectl describe pod -n | grep -A 5 Limits # Get detailed metrics kubectl get --raw /apis/metrics.k8s.io/v1beta1/namespaces//pods/ ``` **Solutions:** - Optimize application code - Adjust resource requests/limits - Scale horizontally with more replicas - Implement caching or performance improvements --- ## Deployment Issues ### Deployment Stuck/Not Rolling Out **Symptoms:** - New version not deployed - Old pods still running - Rollout stuck **Debugging Steps:** ```bash # Check rollout status kubectl rollout status deployment/ -n # Check rollout history kubectl rollout history deployment/ -n # Check replica sets kubectl get rs -n # Check events kubectl get events -n --sort-by='.lastTimestamp' ``` **Solutions:** - Check if new pods are failing (CrashLoopBackOff, ImagePullBackOff) - Verify readiness probes are passing - Check deployment strategy settings - Rollback if needed: `kubectl rollout undo deployment/ -n ` --- ## Issue Resolution Done Criteria Mark troubleshooting complete only when all are true: - [ ] Symptom was matched to one issue section in this file. - [ ] At least one command from `Debugging Steps` produced evidence for the diagnosis. - [ ] Fix was applied and verified with follow-up `kubectl get/describe/logs` checks. - [ ] No new critical warning events appeared after the fix window. - [ ] Any disruptive command used (restart/rollback/force delete) was justified in notes. --- Source: [Claudary](https://claudary.paisolsolutions.com/skills/common-issues-2) · https://claudary.paisolsolutions.com