Helm template rendering fails due to syntax errors, missing variables, or invalid YAML. This prevents chart deployment. Debug by testing templates locally, checking values files, and verifying Helm syntax.
Fixes Helm template error
helm template my-release ./my-chart -f values.yaml
helm template my-release ./my-chart --debughelm template my-release ./my-chart -f values.yamlhelm template my-release ./my-chart --debugHelm template error
On this page
Helm templates are rendered using Go templating language before being sent to Kubernetes. When template errors occur, Helm cannot generate valid Kubernetes manifests. Common causes include undefined variables, incorrect conditionals, invalid YAML indentation, or wrong function usage.
Test template rendering before installing:
helm template my-release ./my-chart -f values.yaml
helm template my-release ./my-chart --debugThis shows the generated manifests.
Validate Go template syntax:
helm lint ./my-chartThis checks for common template and chart issues.
Verify values file is valid YAML:
helm template my-release ./my-chart -f values.yaml --debug | head -50
# Or validate YAML
yaml-lint values.yamlLook for undefined .Values references:
grep -r "\.Values\." ./my-chart/templates/
helm template my-release ./my-chart --debug 2>&1 | grep -i undefinedCheck if/with statements:
{{- if .Values.something }}
key: value
{{- end }}Ensure proper spacing and dash placement for whitespace control.
Try rendering with minimal values:
helm template my-release ./my-chartCheck if issue is in values or templates.
Ensure chart dependencies are installed:
helm dependency update ./my-chart
helm dependency list ./my-chartExamples of valid Helm syntax:
# Variable reference
image: {{ .Values.image.repository }}:{{ .Values.image.tag }}
# Conditional
{{- if .Values.enabled }}
feature: enabled
{{- end }}
# Loops
{{- range .Values.items }}
- name: {{ .name }}
{{- end }}
# Default values
replicas: {{ .Values.replicaCount | default 1 }}Use helm template --debug to see exactly what is being generated. The -x flag limits template rendering to specific files. Named templates (partials) must be in _helpers.tpl. Use sprig functions for advanced text processing (quote, nindent, etc.). For conditional YAML keys, ensure proper indentation with nindent or indent functions.