A helm upgrade fails with "context deadline exceeded" after 7 minutes — is the rollout stuck or just slow?

The first thing to establish about `Error: UPGRADE FAILED: context deadline exceeded` is what it is *not*. Nothing was rejected. No admission webhook denied anything, no field manager conflicted, no hook failed. Helm rendered the chart, applied every object successfully, and then waited for the workload to become ready; `--timeout` expired first and Helm stopped watching. The release is recorded as `failed`, but the cluster holds the **new** manifest, and the controllers are still working. Helm's failure and Kubernetes' progress are two different clocks. ## Reading the clock as evidence If you ran `helm upgrade ... --timeout 7m --wait` and the error came back roughly seven minutes later, the elapsed time equalling the budget is itself the diagnosis: nothing decided to fail, a deadline arrived. A failure at three seconds with the same message would be suspicious; a failure at exactly the budget is the wait. (When you do not pass `--timeout`, it has a default of 5m0s, so an error landing at almost exactly five minutes is the same story with the default budget.) This also distinguishes the case from an operation that never returned at all: a Helm process that was killed mid-flight leaves a release in a pending state, which is a different problem with a different recovery. ## Stuck or slow Having established that Helm merely gave up, the real question is about the workload. Two shapes: | Shape | What the workload shows | The action | | --- | --- | --- | | Slow but converging | Replicas passing readiness one after another | Raise `--timeout` and re-run | | Parked | Crash-looping, unschedulable, never ready | Fix the workload; no timeout helps | *Slow but converging.* New replicas are appearing and passing readiness one after another; images are still being pulled on some nodes; a StatefulSet is rolling one ordinal at a time with a long readiness gate; a large rollout on a small node pool is waiting for capacity to free up. Here the workload will reach ready without your help, the deployment effectively succeeded, and the only defect is the timeout budget. The action is to raise `--timeout` for that chart to something sized from observed rollout times, and to re-run so the release record catches up with reality. *Parked.* Pods are crash-looping, unschedulable, failing a readiness probe forever, or stuck pulling an image that does not exist. No timeout would have helped, and raising it converts a seven-minute failure into a twenty-minute one. The action is to fix the workload. The actual reading of pods, events and probe failures is ordinary Kubernetes triage; the Helm-side judgement is knowing which of the two shapes you are in before you touch a flag. A useful third possibility is that the rollout is blocked on something Helm applied *earlier in the same upgrade* — a ConfigMap or Secret the new pods mount that renders wrong, for example. That still presents as a never-ready workload, but the cause is in the render, and it is worth checking the applied objects rather than only the pods. ## How the wait is implemented, briefly In Helm 4 `--wait` is strategy-valued rather than boolean: - `watcher` is the event-driven waiter and is what a bare `--wait` selects; - `legacy` is Helm 3's polling waiter, whose message for the same situation was `timed out waiting for the condition`; - `hookOnly` waits for hooks only. This matters for triage in one blunt way: **if you omit `--wait` in Helm 4 you get `hookOnly`, so this error class cannot occur** — instead a never-ready workload produces a green upgrade and a `deployed` release over a broken service. Half of "we never see timeouts" is really "we never wait". ## The interaction that bites `--rollback-on-failure` (in Helm 4 `--atomic` is a deprecated alias for it) reverts the release automatically when the upgrade fails, and setting it defaults `--wait` to `watcher`. Combine it with a timeout budget that is shorter than the workload's honest rollout time and you get a loop: the upgrade applies, the rollout is progressing normally, the deadline expires, Helm reverts a perfectly healthy release, and the change never lands. Worse for triage, the revert removes the pods and events you would have inspected. Consider an email-digest builder whose rollout genuinely takes around seven minutes because each replica drains a queue before reporting ready: a 5-minute default plus automatic rollback makes that service undeployable, and the error message blames a deadline rather than the policy that set it. ## Re-running Re-running the same upgrade after a timeout is generally safe for the manifests — applying the same objects again converges to the same state — but every hook in the chart runs again, so the idempotency of those hooks decides whether "just run it again" is really free. The strong answer names the class from the message and the elapsed time, refuses to change a flag before deciding stuck from slow, and knows that raising a timeout is a legitimate fix for exactly one of the two cases.