Helm Debugging & Troubleshooting

Comprehensive guidance for diagnosing and fixing Helm deployment failures, template errors, and configuration issues.

When to Use This Skill

Use this skill when...	Use <sibling> instead when...
Diagnosing template render errors, value type errors, or YAML parse failures	Use helm-release-recovery when the release itself is stuck (pending-install/upgrade) and needs rollback
Inspecting why a chart deployed but pods are crashing or images won't pull	Use kubectl-debugging when you need an ephemeral container or node-level debug session
Running `helm lint`, `helm template`, or `--dry-run` to validate before deploy	Use helm-chart-development when authoring or restructuring a chart from scratch

When to Use

Use this skill automatically when:

User reports Helm deployment failures or errors
User mentions debugging, troubleshooting, or fixing Helm issues
Template rendering problems occur
Value validation or type errors
Resource conflicts or API errors
Image pull failures or pod crashes
User needs to inspect deployed resources

Context Safety (CRITICAL)

Always specify --context explicitly in all kubectl and helm commands. Never rely on the current context.

# CORRECT: Explicit context
kubectl --context=prod-cluster get pods -n prod
helm --kube-context=prod-cluster status myapp -n prod

# WRONG: Relying on current context
kubectl get pods -n prod  # Which cluster?

This prevents accidental operations on the wrong cluster.

Layered Validation Approach

ALWAYS follow this progression for robust deployments:

# 1. LINT - Static analysis (local charts only)
helm lint ./mychart --strict

# 2. TEMPLATE - Render templates locally
helm template myapp ./mychart \
  --debug \
  --values values.yaml

# 3. DRY-RUN - Server-side validation
helm install myapp ./mychart \
  --namespace prod \
  --values values.yaml \
  --dry-run --debug

# 4. INSTALL - Actual deployment
helm install myapp ./mychart \
  --namespace prod \
  --values values.yaml \
  --atomic --wait

# 5. TEST - Post-deployment validation (if chart has tests)
helm test myapp --namespace prod --logs

Core Debugging Commands

Template Rendering & Inspection

# Render all templates locally
helm template myapp ./mychart \
  --debug \
  --values values.yaml

# Render specific template file
helm template myapp ./mychart \
  --show-only templates/deployment.yaml \
  --values values.yaml

# Render with debug output (shows computed values)
helm template myapp ./mychart \
  --debug \
  --values values.yaml \
  2>&1 | less

# Validate against Kubernetes API (dry-run)
helm install myapp ./mychart \
  --namespace prod \
  --values values.yaml \
  --dry-run \
  --debug

Inspect Deployed Resources

# Get deployed manifest (actual YAML in cluster)
helm get manifest myapp --namespace prod

# Get deployed values (what was actually used)
helm get values myapp --namespace prod

# Get ALL values (including defaults)
helm get values myapp --namespace prod --all

# Get release status with resources
helm status myapp --namespace prod --show-resources

# Get everything about a release
helm get all myapp --namespace prod

Chart Validation

# Lint chart structure and templates
helm lint ./mychart

# Lint with strict mode (treats warnings as errors)
helm lint ./mychart --strict

# Lint with specific values
helm lint ./mychart --values values.yaml --strict

# Validate chart against Kubernetes API
helm install myapp ./mychart \
  --dry-run --validate --namespace prod

Verbose Debugging

# Enable Helm debug logging
helm install myapp ./mychart \
  --namespace prod \
  --debug \
  --dry-run

# Enable Kubernetes client logging
helm install myapp ./mychart \
  --namespace prod \
  --v=6  # Verbosity level 0-9

Common Failure Scenarios

Scenario	Symptom	Quick Fix
YAML parse error	`error converting YAML to JSON`	Check indentation, use `{{- ... }}` for whitespace chomping
Template rendering error	`nil pointer evaluating interface`	Add defaults: `{{ .Values.key \| default "value" }}`
Value type error	`cannot unmarshal string into Go value of type int`	Use `{{ .Values.port \| int }}` in template
Resource already exists	`resource that already exists`	`helm uninstall` conflicting release or adopt resource
Image pull failure	`ImagePullBackOff`	Fix image name/tag, create pull secret
CRD not found	`no matches for kind`	Install CRDs first: `kubectl apply -f crds/`
Timeout	`timed out waiting for the condition`	Increase `--timeout`, check readiness probes
Hook failure	`pre-upgrade hooks failed`	Delete failed hook job, retry with `--no-hooks`

For detailed debugging steps, fixes, and examples for each failure scenario, see REFERENCE.md.

Agentic Optimizations

Context	Command
Release status (JSON)	`helm status <release> -n <ns> -o json`
All values (JSON)	`helm get values <release> -n <ns> --all -o json`
Pod status (compact)	`kubectl get pods -n <ns> -l app.kubernetes.io/instance=<release> -o wide`
Events (sorted)	`kubectl get events -n <ns> --sort-by='.lastTimestamp' -o json`
Render + validate	`helm template <release> ./chart --debug 2>&1 \| head -100`

Related Skills

Helm Release Management - Install, upgrade, uninstall operations
Helm Values Management - Advanced configuration management
Helm Release Recovery - Rollback and recovery strategies
Kubernetes Operations - Managing and debugging K8s resources
ArgoCD CLI Login - GitOps debugging with ArgoCD

helm-debugging