Helm "UPGRADE FAILED: cannot patch ... field is immutable"

Helm upgrades by patching existing objects. When a chart change touches an immutable field - a Deployment selector, a Job template, a Service clusterIP - the API server rejects the patch, and Helm reports cannot patch ... field is immutable.

What this error means

helm upgrade fails with Error: UPGRADE FAILED: cannot patch "<name>" with kind <Kind>: <Kind> "<name>" is invalid: spec.<field>: Invalid value: ...: field is immutable.

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

Chart changed an immutable selector/template

Editing spec.selector.matchLabels (Deployment/StatefulSet) or a Job’s spec.template in the chart produces a patch the API server forbids on the existing object.

Service clusterIP or other locked field changed

A change to Service.spec.clusterIP or another field fixed at creation cannot be patched in place during the upgrade.

How to fix it

Recreate the object instead of patching it

For immutable fields, delete the conflicting resource so the next Helm upgrade re-creates it with the new spec.

Terminal

kubectl delete deployment api -n <ns>
helm upgrade --install api ./chart -n <ns>

Keep immutable fields stable in the chart

Never change spec.selector labels on an existing Deployment/StatefulSet via the chart.
For Jobs, render a new name (e.g. include a hash) so each run is a new object.
Diff before upgrading: helm diff upgrade (helm-diff plugin) to catch immutable changes.

How to prevent it

Decide selector labels once and keep them constant across chart versions.
Use helm diff upgrade in CI to catch immutable-field changes before they fail.
Recreate (blue/green) rather than mutate when an immutable field must change.