kubectl "context deadline exceeded" on rollout/wait in CI

kubectl wait/rollout status blocks until a condition is met or its timeout elapses. "context deadline exceeded" means the deadline hit first - the resource did not become ready in time, or the API call itself stalled.

What this error means

A kubectl rollout status or kubectl wait step in CI fails with "context deadline exceeded", because the deployment/pod never reached the awaited condition within --timeout.

kubectl

error: timed out waiting for the condition

# or, with an explicit context timeout:
Unable to connect to the server: context deadline exceeded (Client.Timeout
exceeded while awaiting headers)

Common causes

Resource never reaches the condition

Pods stay not-Ready (probes, crashes, scheduling), so the wait times out.

Timeout shorter than real startup

A slow app needs more time than the configured --timeout.

API server slow or unreachable

A transient API slowdown or network blip makes the underlying call exceed its deadline.

How to fix it

Inspect why the condition is unmet

Find the real blocker before extending timeouts.

Terminal

kubectl rollout status deploy/api --timeout=5m
kubectl get pods -l app=api -o wide
kubectl describe pod <pod>

Set a realistic timeout, fix the blocker

Raise --timeout to match the app's genuine startup time.
Fix probe/scheduling/image issues keeping pods not-Ready.
Retry if the failure was a transient API-server stall.

How to prevent it

Use timeouts sized to real rollout time, not arbitrary defaults.
Make readiness probes accurate so waits resolve promptly.
Ensure stable connectivity to the API server from the runner.