criticalIntermediateUSE#helm#upgrade#timeout#readiness#wait

Helm upgrade timeout — context deadline exceeded while waiting for resources

Error: context deadline exceeded — Helm upgrade times out waiting for resources

Likely source:deploymentperformanceavailability

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Error: context deadline exceeded — Helm upgrade times out waiting for resources
  • Helm upgrade shows 'waiting for rollout to finish' then fails after timeout
  • upgrade --wait hangs for 5 minutes before reporting failure

A Helm timeout does NOT roll back by default — it leaves the release in pending-upgrade. You must manually recover or rollback.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Helm release status after timeout

    helm status <RELEASE> -n <NAMESPACE>

  • Deployment rollout status

    kubectl rollout status deployment/<RESOURCE> -n <NAMESPACE> --timeout=60s

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • kubectl describe shows Readiness probe failed repeatedly
  • New pods appear but never transition to Running/Ready
  • App logs show startup errors or missing dependencies

Confirm before fixing

kubectl describe pod <STUCK_POD> -n <NAMESPACE> | grep -A5 'Readiness'
READ

Read the readiness probe configuration and failure messages

Expected: Readiness probe failed: HTTP probe failed with statuscode: 503

Fix

kubectl patch deployment/<RESOURCE> -n <NAMESPACE> --type merge -p '{"spec":{"template":{"spec":{"containers":[{"name":"<CONTAINER>","readinessProbe":{"initialDelaySeconds":30,"periodSeconds":10,"failureThreshold":5}}}]}}}'
CHANGE

Relax the readiness probe to allow more startup time

Expected: deployment.apps/<RESOURCE> patched

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
helm status <RELEASE> -n <NAMESPACE>
READ

Check the current release state and error

2
kubectl get deploy,job,pod -n <NAMESPACE> -l app.kubernetes.io/instance=<RELEASE>
READ

Find which resource is not becoming Ready

3
kubectl rollout status deployment/<RESOURCE> -n <NAMESPACE> --timeout=30s
READ

Confirm the rollout is stuck

4
kubectl logs <STUCK_POD> -n <NAMESPACE> --previous | tail -50
READ

Read the crash or startup logs

5
helm upgrade --reuse-values <RELEASE> <CHART> -n <NAMESPACE> --timeout 10m
CHANGE

Re-run the upgrade with a longer timeout after fixing the root cause

Expected: Release "<RELEASE>" has been upgraded

Prevention

  • Set --timeout to at least 2x your worst-case deployment startup time in CI/CD.
  • Use helm test after install/upgrade to validate readiness in a separate step.
  • Add startupProbe for slow-starting applications instead of relying solely on readinessProbe.
  • Monitor rollout time and alert when it approaches the configured Helm timeout.

Related runbooks

Same stack, same failure family — worth a skim.

CrashLoopBackOff — container keeps crashing and restartingcritical

kubectl get pods shows CrashLoopBackOff status

KubernetesFoundation4 causes
Open runbook
Pods stuck in Pending state — unschedulablehigh

kubectl get pods shows Pending for minutes

KubernetesIntermediate3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.