kubectl wait "timed out waiting for the condition" - Fix in CI

By Daniel Zoghalchali·Latchkey

kubectl wait polled for a condition (Ready, Available, Established) until --timeout and the object never satisfied it. Sometimes the object is genuinely stuck; sometimes the timeout is just shorter than how long the resource legitimately takes - a transient slow start that passes with more time.

What this error means

kubectl wait --for=condition=... <resource> --timeout=Ns exits non-zero with error: timed out waiting for the condition on <resource>/<name>. A re-run with the object already healthy, or a longer timeout, often succeeds.

kubectl output

error: timed out waiting for the condition on deployments/api
# or
error: timed out waiting for the condition on pods/db-0

Common causes

Timeout shorter than real readiness time

A slow image pull, a long migration, or a heavy app boot makes the object reach its condition later than the --timeout allows - a transient timing miss that clears with a longer budget or a retry.

The object never reaches the condition

A crashing pod, a failing probe, an unschedulable workload, or a CRD that never becomes Established will never satisfy the wait, no matter how long.

How to fix it

Distinguish slow from stuck

While the wait is failing, look at the object’s real state. If it is progressing, give it more time; if it is crashing/Pending, fix the root cause.

Terminal

kubectl wait --for=condition=Available deploy/api --timeout=180s
kubectl get pods -l app=api
kubectl describe deploy/api | sed -n '/Conditions/,/Events/p'

Raise the timeout for legitimately slow resources

When the resource is healthy but slow, a longer --timeout (and a bounded retry) absorbs the transient delay.

Terminal

for i in 1 2 3; do
  kubectl wait --for=condition=Established crd/widgets.example.com --timeout=120s && break
  sleep 5
done

How to prevent it

Set --timeout to the resource’s realistic worst-case readiness time.
Wait on the right condition (Available for Deployments, Established for CRDs, Ready for pods).
Wrap waits in a bounded retry so a transient slow start does not fail the pipeline.

Frequently asked questions

What causes ""timed out waiting for the condition""?

A slow image pull, a long migration, or a heavy app boot makes the object reach its condition later than the --timeout allows - a transient timing miss that clears with a longer budget or a retry.

How do I fix "timed out waiting for the condition"?