Helm "UPGRADE FAILED" - Diagnose and Fix Failed Upgrades in CI

UPGRADE FAILED is Helm’s wrapper; the real cause follows the colon - a failed hook, an invalid or immutable resource, or a timeout waiting for readiness. Read the suffix to know what to fix.

What this error means

helm upgrade exits non-zero with Error: UPGRADE FAILED: <specific reason>. The release may be left in failed state, and with --atomic it rolls back automatically.

helm output

Error: UPGRADE FAILED: cannot patch "api" with kind Deployment:
Deployment.apps "api" is invalid: spec.selector: Invalid value: ...: field is
immutable

Common causes

An invalid or immutable resource

A rendered manifest fails server validation, or it changes an immutable field (Deployment selector, Service clusterIP), so the patch is rejected.

A pre/post hook failed

A helm.sh/hook Job (migration, test) failed or timed out, which fails the whole upgrade.

Timed out waiting for readiness

With --wait, Helm waits for resources to become Ready; if pods crash or never schedule, the upgrade fails on timeout.

How to fix it

Read the suffix and inspect history

The text after UPGRADE FAILED: is the real error. Use history and status to see the failed revision.

Terminal

helm history <release> -n <ns>
helm status <release> -n <ns>
helm upgrade <release> ./chart -n <ns> --debug --dry-run

Fix by cause class

Immutable/invalid resource → correct the manifest (and recreate the object if the field is immutable).
Failed hook → inspect the hook Job’s pod logs and fix the underlying job.
Readiness timeout → diagnose the crashing/Pending pods, then re-run.

Make upgrades self-cleaning

Use atomic upgrades so a failure rolls back instead of leaving a broken release.