Kubernetes StatefulSet Pod Not Starting: 6 Causes and Fixes

# Check pod status
kubectl get pods -n <namespace> -l app=<your-statefulset>
 
# Check StatefulSet status
kubectl describe statefulset <name> -n <namespace>
 
# Check events
kubectl get events -n <namespace> --sort-by=.lastTimestamp | tail -20

kubectl get pvc -n <namespace>
# Look for STATUS = Pending instead of Bound

kubectl get storageclass
# If no StorageClass has (default) annotation, PVC will never bind
 
# Fix: set a default
kubectl patch storageclass gp2 -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

kubectl describe pvc <pvc-name> -n <namespace>
# Events: waiting for first consumer to be created before binding
 
# This is normal — the PVC binds when the pod schedules
# If pod won't schedule, the PVC waits forever
# Check node selector or taints blocking pod placement
kubectl describe pod <pod-name> -n <namespace> | grep -A 5 "Events:"

kubectl get pods -n kube-system | grep provisioner
# If EBS CSI driver, check:
kubectl get pods -n kube-system | grep ebs-csi

kubectl get svc -n <namespace>
# Look for your headless service — CLUSTER-IP should be "None"
 
kubectl describe statefulset <name> -n <namespace> | grep serviceName
# This must match an existing headless service

apiVersion: v1
kind: Service
metadata:
  name: postgres-headless
  namespace: production
spec:
  clusterIP: None          # This is what makes it headless
  selector:
    app: postgres
  ports:
  - port: 5432
    name: postgres

kubectl apply -f headless-svc.yaml

# From another pod in the same namespace
kubectl run -it --rm debug --image=busybox --restart=Never -- nslookup postgres-0.postgres-headless.production.svc.cluster.local

kubectl describe pod postgres-0 -n <namespace>
# Look for init container status
 
kubectl logs postgres-0 -n <namespace> -c <init-container-name>
# Check init container logs

# Permission fix init container failing
# Check if the target volume is read-only or wrong owner
 
# Database migration init container failing
# Check database connectivity from init container
kubectl exec -it postgres-0 -c <init-container> -- /bin/sh
# Try connecting to dependencies manually

kubectl get pod postgres-0 -n <namespace> -o jsonpath='{.status.conditions[?(@.type=="Ready")].status}'
# If False, pod-0 is Running but not Ready

readinessProbe:
  exec:
    command:
    - /bin/sh
    - -c
    - pg_isready -U postgres
  initialDelaySeconds: 30   # Give DB time to start
  periodSeconds: 10
  failureThreshold: 6        # Allow more failures before marking unready

kubectl describe pod postgres-0 -n <namespace> | grep -A 10 "Events:"
# Look for: Insufficient cpu, Insufficient memory
 
# Check node capacity
kubectl describe nodes | grep -A 5 "Allocated resources:"
 
# Fix: reduce resource requests or add nodes

kubectl describe pod postgres-0 -n <namespace> | grep -A 20 "Node-Selectors:"

kubectl get statefulset <name> -n <namespace> -o jsonpath='{.spec.podManagementPolicy}'

spec:
  podManagementPolicy: Parallel   # Start all pods simultaneously

# 1. StatefulSet conditions
kubectl describe statefulset <name> -n <namespace>
 
# 2. Pod status for all replicas
kubectl get pods -n <namespace> -l app=<name> -o wide
 
# 3. PVC status
kubectl get pvc -n <namespace> | grep <name>
 
# 4. Headless service
kubectl get svc -n <namespace> | grep None
 
# 5. Events
kubectl get events -n <namespace> --sort-by=.lastTimestamp | grep <name>
 
# 6. Pod logs (including previous container)
kubectl logs <pod-name> -n <namespace> --previous
 
# 7. Init container logs
kubectl logs <pod-name> -n <namespace> -c <init-container-name>
 
# 8. Node resources
kubectl describe nodes | grep -E "Name:|Allocated"