Common Kubernetes Failure Modes

A practical field guide for recognizing common Kubernetes failure modes and knowing which commands to run first.

Kubernetes Field Notes · Reference Guide

How to use this page

Use this page when something is broken and you need a practical path from symptom to likely cause.

Universal first checks

kubectl config current-context
kubectl config view --minify --output 'jsonpath={..namespace}'
kubectl get pods -A
kubectl get events -A --sort-by=.metadata.creationTimestamp

Pod stuck Pending

Usually means: Kubernetes accepted the Pod, but the scheduler cannot place it or required resources are not available.

kubectl describe pod <pod-name> -n <namespace>
kubectl get events -n <namespace> --sort-by=.metadata.creationTimestamp
kubectl describe node <node-name>
kubectl get pvc -n <namespace>

• Resource requests are too high.
• Node selector or affinity matches no node.
• Taints exist and the Pod lacks tolerations.
• A PVC is not bound.

ImagePullBackOff or ErrImagePull

Usually means: Kubernetes cannot pull the container image.

kubectl describe pod <pod-name> -n <namespace>
kubectl get events -n <namespace> --sort-by=.metadata.creationTimestamp

• Image name is wrong.
• Tag does not exist.
• Registry credentials are missing.
• Node cannot reach the registry.

CrashLoopBackOff

Usually means: The container starts, exits, and Kubernetes keeps trying to restart it.

kubectl logs <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous
kubectl describe pod <pod-name> -n <namespace>

• Application error on startup.
• Bad command or args.
• Missing ConfigMap, Secret, or environment value.
• Liveness probe is too aggressive.

Running but not Ready

Usually means: The container process is running, but readiness is failing.

kubectl get pods -n <namespace>
kubectl describe pod <pod-name> -n <namespace>
kubectl get endpoints <service-name> -n <namespace>

• Readiness probe path or port is wrong.
• Application is not ready yet.
• Dependency check is failing.
• Pods are not Ready, so Service endpoints are missing.

OOMKilled

Usually means: The container exceeded its memory limit.

kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace> --previous
kubectl get pod <pod-name> -n <namespace> -o yaml

Service has no endpoints

Usually means: The Service exists, but no ready Pods match its selector.

kubectl describe service <service-name> -n <namespace>
kubectl get endpoints <service-name> -n <namespace>
kubectl get pods --show-labels -n <namespace>

• Service selector does not match Pod labels.
• Pods are not Ready.
• Pods are in a different Namespace.

Ingress returns 404

Usually means: The request reached the ingress controller, but no Ingress rule matched the host/path.

• Host header does not match.
• Path does not match.
• Ingress class mismatch.

Ingress returns 502 or 503

Usually means: The route matched, but the backend Service or Pods are unavailable.

kubectl get endpoints <service-name> -n <namespace>
kubectl describe service <service-name> -n <namespace>
kubectl get pods -n <namespace>
kubectl describe pod <pod-name> -n <namespace>

ConfigMap or Secret not found

Usually means: The Pod references an object that does not exist in the same Namespace or uses the wrong key.

kubectl describe pod <pod-name> -n <namespace>
kubectl get configmaps -n <namespace>
kubectl get secrets -n <namespace>

PVC stuck Pending

Usually means: Kubernetes cannot bind or provision the requested storage.

kubectl get pvc -n <namespace>
kubectl describe pvc <pvc-name> -n <namespace>
kubectl get storageclass
kubectl get pv

Rollout stuck

Usually means: New Pods are not becoming available.

kubectl rollout status deployment/<deployment-name> -n <namespace>
kubectl describe deployment <deployment-name> -n <namespace>
kubectl get pods -n <namespace>
kubectl describe pod <new-pod-name> -n <namespace>

Common recovery:

kubectl rollout undo deployment/<deployment-name> -n <namespace>

RBAC forbidden

Usually means: The user or ServiceAccount is authenticated but not authorized.

kubectl auth can-i <verb> <resource> -n <namespace>
kubectl auth can-i <verb> <resource> --as=system:serviceaccount:<namespace>:<serviceaccount> -n <namespace>
kubectl get rolebindings -n <namespace>

NetworkPolicy blocking traffic

Usually means: NetworkPolicy is denying needed traffic, assuming the CNI enforces policy.

kubectl get networkpolicies -n <namespace>
kubectl describe networkpolicy <policy-name> -n <namespace>
kubectl get pods --show-labels -n <namespace>
kubectl get namespaces --show-labels