Troubleshooting Releases

The usual suspects

Most Helm problems fall into a few groups. Template errors ("nil pointer evaluating interface", "YAML parse error") come from missing values or bad indentation: render with helm template --debug and check the line it names. Immutable field errors ("spec.selector: field is immutable") come from changing a Deployment selector or a Job template; the object must be recreated. Ownership conflicts ("exists and cannot be imported into the current release") mean an object already exists without Helm's meta.helm.sh/release-name and release-namespace annotations, often created by kubectl apply or another release. Stuck releases with status pending-install, pending-upgrade or pending-rollback usually follow an interrupted command (a cancelled CI job); Helm refuses new operations until you roll back to the last good revision. Failed readiness under --wait is a Kubernetes problem: inspect pods, events and logs, not Helm.

From symptom to cause

Start from the error message, check rendered YAML, then cluster state.

A troubleshooting session

Work from Helm's view of the release down to the pods.

helm status shop-api -n shop            # current status and last error
helm history shop-api -n shop           # which revision failed, and why
helm get values shop-api -n shop --all  # what values were actually used
helm get manifest shop-api -n shop | kubectl diff -f - # compare with live objects

# stuck in pending-upgrade after a cancelled job
helm rollback shop-api 4 -n shop

# release looks fine but pods do not start: it is a Kubernetes problem now
kubectl get pods -n shop -l app.kubernetes.io/instance=shop-api
kubectl describe pod -n shop <pod>
kubectl logs -n shop <pod> --previous

Do not delete release Secrets to unstick things

Deleting sh.helm.release.v1.* Secrets makes Helm forget objects that still exist, which then cause ownership conflicts on the next install. Roll back to a good revision instead.

Quick check: A CI job was cancelled during an upgrade and the release now shows pending-upgrade. What is the usual fix?

• Delete the namespace
• Run helm repo update
• Roll back to the last successful revision
• Edit the release Secret by hand