helm-debugging

Helm Debugging & Troubleshooting

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

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

References

• Helm Debugging Documentation
• Helm Troubleshooting Guide
• Kubernetes Debugging
• Template Function Reference