helm-debugging

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 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

References

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