# Troubleshooting Releases — Helm

Source: https://www.skillbyai.com/en/helm/p-troubleshoot

> Diagnose failed, stuck and conflicting 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 branching path from a warning symbol into three routes, each ending at a different tool icon shape.](assets/figures/helm/section-8-map.svg) — Figure 8.1 — Triage paths for template, apply and runtime failures.

## A troubleshooting session

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

```bash
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.

**Quiz:** 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
- [x] Roll back to the last successful revision
- [ ] Edit the release Secret by hand

*Answer:* Roll back to the last successful revision. Rolling back to a known-good revision clears the pending state through a normal Helm operation.