Pod-level errors — the first place to look

1. CrashLoopBackOff

Pod starts, crashes, K8s waits (10s, 20s, 40s… hence "backoff") and tries again.

kubectl logs <pod> --previous     # what did the last run say?
kubectl describe pod <pod>        # Events section at bottom

Root causes: app bug, missing env var, missing config file, wrong entrypoint.

2. ImagePullBackOff / ErrImagePull

K8s cannot download the image.

kubectl describe pod <pod>        # look for "Failed to pull image ..."
kubectl get events                # confirms the pull error

Checklist:

• Typo in image name or tag?
• Image actually exists in the registry?
• Private registry → is imagePullSecrets set on the ServiceAccount?

3. Pod stuck in Pending

Scheduler can't place it anywhere.

kubectl describe pod <pod>        # scroll to Events

Common events: "insufficient cpu/memory", "no nodes match taints", "unbound PersistentVolumeClaims". Reduce resources.requests, add nodes, or fix the PVC.

4. Init container CrashLoop

The init container itself is failing → main container never starts.

kubectl logs <pod> -c <init-container-name>

5. OOMKilled (out of memory)

Kernel killed the container because it went over its memory limit.

kubectl describe pod <pod>        # Last State: Terminated, Reason: OOMKilled

Bump resources.limits.memory or fix the memory leak.

6. Node evicts your pod (Evicted)

Node was under memory / disk pressure. Move workload to a bigger node, set proper requests, or add nodes so the scheduler has room.

7. Liveness probe fails → constant restart

Probe endpoint too slow or wrong path.

livenessProbe:
  httpGet: { path: /healthz, port: 8080 }
  initialDelaySeconds: 30      # give the app time to boot
  periodSeconds: 10
  failureThreshold: 3

8. Readiness probe fails → pod not getting traffic

Same fix — but the pod stays alive, just doesn't receive traffic. Check with kubectl get endpoints <svc> — if empty, readiness is failing.

9. ConfigMap / Secret mount errors

Pod events say MountVolume.SetUp failed. Checklist:

• Does the ConfigMap/Secret exist in the same namespace?
• Is the key you referenced in the pod actually a key inside the CM/Secret?

10. Secret decoding errors

App reads the secret but it's base64-double-encoded or has extra newlines.

echo "encodedstring" | base64 -d

11. Volume mount permission denied

Container UID doesn't match volume ownership. Fix with securityContext.fsGroup on the pod, or an initContainer that chowns the mount.

12. Pods stuck in Terminating forever

Usually a finalizer hanging on. Diagnose:

kubectl get pod <p> -o yaml | grep finalizers -A5

If safe, force it:

kubectl delete pod <p> --grace-period=0 --force

13. RunContainerError / CreateContainerConfigError

Some field the pod references doesn't exist (missing env-var source, missing PVC).

14. Invalid pod restart policy

Only Always | OnFailure | Never allowed. Deployments require Always.

15. PodSecurityContext rejected

Cluster admits only unprivileged pods; your pod asked for privileged: true or hostPath. Adjust the pod or the PodSecurity policy.

Real-world example

A Java service throws OOMKilled every night at 2 AM. You add -XX:+HeapDumpOnOutOfMemoryError, mount an emptyDir at /dumps, next crash you kubectl cp the heap dump out, load in Eclipse MAT → a cache without eviction. One-line fix. Sleep restored.

Debug flow diagram

Pod unhappy?
   │
   ├── kubectl describe pod   → any obvious event?  Fix it.
   │
   ├── kubectl logs (--previous)  → what did the app say?
   │
   ├── kubectl exec -it -- sh  → is the file/env/permission there?
   │
   └── Still stuck?  Move to Part 2 (networking).