Introduction

Helm templates use Go's text/template engine to render Kubernetes manifests from chart templates and values. When a template references a value that is nil or missing from the values.yaml file or the --set overrides, the template rendering fails with a nil pointer error. This prevents any resources from being created or updated.

Symptoms

  • helm install or helm template fails with nil pointer evaluating interface
  • Error message points to the specific template file and line number
  • Chart works with default values but fails with custom values overrides
  • Template uses .Values.config.setting but config or setting is not defined
  • Error message: error calling include: template: no value "myValue" in .Values

Common Causes

  • Values override file missing a required key that the template expects
  • Typo in the value path (e.g., .Values.replicaCcount instead of .Values.replicaCount)
  • Conditional template block not checking for nil before accessing nested values
  • Merged values from multiple override files creating unexpected nil values
  • Helm subchart values not properly namespaced under the subchart name

Step-by-Step Fix

  1. 1.Identify the nil value from the error message: Find the missing key.
  2. 2.```bash
  3. 3.helm template my-release ./chart -f values.yaml 2>&1 | grep -i "nil"
  4. 4.`
  5. 5.Check the values.yaml for the missing key: Verify the value exists.
  6. 6.```bash
  7. 7.yq eval '.image.repository' values.yaml
  8. 8.# Returns null if the key is missing
  9. 9.`
  10. 10.Add the missing value with a default: Update values.yaml.
  11. 11.```yaml
  12. 12.# values.yaml
  13. 13.image:
  14. 14.repository: myapp
  15. 15.tag: "1.0.0"
  16. 16.pullPolicy: IfNotPresent
  17. 17.`
  18. 18.Add nil checks in the template for optional values: Make the template resilient.
  19. 19.```yaml
  20. 20.# templates/deployment.yaml
  21. 21.{{- if .Values.config }}
  22. 22.env:
  23. 23.{{- range $key, $value := .Values.config }}
  24. 24.- name: {{ $key }}
  25. 25.value: {{ $value | quote }}
  26. 26.{{- end }}
  27. 27.{{- end }}
  28. 28.`
  29. 29.**Use the default function for values with sensible defaults**: Provide fallback values.
  30. 30.```yaml
  31. 31.replicas: {{ .Values.replicaCount | default 1 }}
  32. 32.image: {{ .Values.image.repository | default "nginx" }}:{{ .Values.image.tag | default "latest" }}
  33. 33.`

Prevention

  • Define all required values with defaults in the chart's default values.yaml
  • Use required function for mandatory values with clear error messages
  • Run helm lint and helm template in CI/CD pipelines before any install or upgrade
  • Maintain a schema.json file for values validation with helm schema plugin
  • Document all required and optional values in the chart's README with examples
  • Test chart rendering with minimal values (only required keys) to catch nil references