helm-debugging
Debug Helm failures — template errors, dry-run, YAML parse errors, value type errors, resource conflicts. Use when the user mentions Helm errors or template rendering issues.
How do I install this agent skill?
npx skills add https://github.com/laurigates/claude-plugins --skill helm-debuggingIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides standard debugging procedures for Helm and Kubernetes deployments. It emphasizes context safety and validation steps. The primary security consideration is the potential for indirect prompt injection when the agent reads application logs or cluster events, which are untrusted data sources.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
2/2 files flagged
What does this agent skill do?
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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/laurigates/claude-plugins/helm-debugging">View helm-debugging on skillZs</a>