Helm troubleshooting

Install or upgrade failed (exit non-zero)

Run helm status RELEASE -n NS and helm history RELEASE -n NS. Helm often leaves a failed revision recorded. Check rendered resources: helm get manifest RELEASE -n NS. Then debug workloads with kubectl — kubectl get pods -n NS -l app.kubernetes.io/instance=RELEASE and kubectl describe pod. Use stern (krew) for logs: stern -l app.kubernetes.io/instance=RELEASE -n NS.

Release stuck in pending-install / pending-upgrade

Interrupted CLI or hook Job hanging. Check hook pods: kubectl get pods -n NS -l helm.sh/hook. Delete stuck hook Jobs if safe, then retry or rollback. Last resort on Helm 3: helm rollback RELEASE REV -n NS. For persistent lock issues, inspect release Secrets: kubectl get secret -n NS -l owner=helm (label varies by version).

Wrong configuration after upgrade

Compare effective values: helm get values RELEASE -n NS vs your intended values.yaml. Remember merge order: chart defaults < multiple -f files (last wins) < --set. Roll back quickly: helm history RELEASE -n NS then helm rollback RELEASE PREVIOUS_REV -n NS.

Chart not found / repo errors

helm repo update then helm search repo CHART. Typo in chart name or stale index. For OCI: verify oci:// path and --version. Air-gapped environments need local .tgz: helm install RELEASE ./chart-1.0.0.tgz.

Template render errors

Run helm template RELEASE ./chart -f values.yaml --debug to see failing template and YAML. Common causes: nil pointer in values (missing key), invalid YAML after render, or wrong indentation in templates. Fix values.yaml or chart templates; validate with helm lint.

RBAC / Forbidden during install

Helm uses your kubeconfig user or ServiceAccount — same RBAC as kubectl. Test: kubectl auth can-i create deployments -n NS. CI pipelines need a Role with permissions for all resource types the chart creates (CRDs, webhooks, etc.).

Hook failed (pre/post install or upgrade)

Hooks run as Kubernetes Jobs or Pods. Find them: kubectl get jobs,pods -n NS -l helm.sh/hook. Read logs: kubectl logs job/HOOK_JOB -n NS or stern. Fix hook script or disable hooks temporarily only if you understand side effects (--no-hooks on upgrade — use with caution).

Resources left after uninstall

Resources annotated helm.sh/resource-policy: keep survive uninstall (common for PVCs). Delete manually if intended. CRDs installed by chart may remain — remove with care. helm uninstall removes Helm-managed objects for that release label.

Pods healthy but app broken

That is application/config debugging, not Helm-specific. Verify ConfigMaps and Secrets from values: helm get values RELEASE -n NS. Exec into pod, check env and mounted files. Ingress and service issues: see Kubernetes and ingress labs.

Debugging workflow

1. Release state

2. What was deployed

3. Cluster objects and logs