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

References

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