KubeErrors

StatefulSet pod stuck: One pod is blocking every pod after it in the ordinal sequence

A StatefulSet creates and updates pods in order and waits for each to be Ready. A pod that never becomes Ready halts the whole sequence, so a single failure stops the rest of the set.

Applies to: All Kubernetes versions

What it means

StatefulSets provide ordering guarantees: pods are created from ordinal 0 upward, each waiting for its predecessor to be Running and Ready, and updated from the highest ordinal downward. These guarantees are the reason to use a StatefulSet, and they are also why one bad pod stops everything. If pod 2 never becomes Ready, pods 3 and above are never created; during a rolling update, if the newly updated highest-ordinal pod never becomes Ready, the update stops there and the remaining pods stay on the old version. Nothing times out — the controller waits indefinitely, because proceeding would break the guarantee it exists to provide.

Most common causes

How to diagnose it

  1. Find the lowest-numbered pod that is not Ready: kubectl get pods -l app=NAME — the ordinals make the blocking pod obvious.
  2. Describe that specific pod, not the StatefulSet: kubectl describe pod NAME-N.
  3. Check its volume claim: kubectl get pvc, since each ordinal has its own.
  4. Check the update strategy and partition: kubectl get statefulset NAME -o jsonpath='{.spec.updateStrategy}'.
  5. For an unreachable node, confirm whether the original pod is genuinely gone before doing anything that would create a second copy.

How to fix it

  1. Fix the blocking pod. Everything after it resumes automatically.
  2. Resolve volume attachment problems, usually by ensuring the previous pod has fully terminated.
  3. Roll back a bad update by setting the template back — the controller works downward from the highest ordinal.
  4. Use podManagementPolicy: Parallel if the workload does not actually need ordered startup. Many do not, and it removes this failure mode entirely.
  5. For a pod stranded on a dead node, deleting the node object is the safe way to release it. Force-deleting the pod risks two instances with the same identity, which is exactly what the ordering guarantee prevents.

Notes

Force-deleting a StatefulSet pod removes the API object without confirming the container stopped. For a database, that can mean two processes writing the same data. The conservative behaviour is the feature, and working around it should be a deliberate decision.

Related

Sources

Pages on this site are written with AI assistance from the primary sources listed on each page, then checked against those sources before publishing.