highIntermediateSymptom-first#helm#template#values#nil-pointer#render

Helm template render error — nil pointer evaluating missing .Values

Error: template: <chart>: ... nil pointer evaluating interface {}

Likely source:configurationdeployment

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Error: template: <chart>: ... nil pointer evaluating interface {}
  • Error: template: <chart>: ... index out of range: 0 with length 0
  • helm template fails locally but helm install succeeded in another environment

Helm template errors are template-time, not runtime — they happen before anything touches the cluster. Always run helm template locally as a pre-deploy gate.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Template render error message

    helm template <RELEASE> <CHART> -n <NAMESPACE> -f values.yaml 2>&1

  • Values file contents

    cat values.yaml | grep -A5 <MISSING_KEY>

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • Error appeared after bumping the chart version
  • New required values exist in the chart's default values.yaml but not in the user's file
  • Values.yaml is missing a top-level key that the template references

Confirm before fixing

helm show values <CHART> | grep -c '<MISSING_KEY>'
READ

Check if the chart default values contain the missing key

Expected: 1 or more matches

Fix

helm show values <CHART> > /tmp/defaults.yaml && diff values.yaml /tmp/defaults.yaml
READ

Compare to find the missing keys

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
helm template <RELEASE> <CHART> -n <NAMESPACE> -f values.yaml 2>&1 | grep 'nil pointer'
READ

Reproduce the error and extract the missing value path

2
helm show values <CHART> > /tmp/defaults.yaml && diff values.yaml /tmp/defaults.yaml
READ

Compare your values against the chart defaults

3
helm install <RELEASE> <CHART> -n <NAMESPACE> -f values.yaml --dry-run
CHANGE

Validate the fix with a dry-run before applying

Expected: NAME: <RELEASE>, STATUS: pending-install

4
helm upgrade <RELEASE> <CHART> -n <NAMESPACE> -f values.yaml
CHANGE

Apply the corrected values

Expected: Release "<RELEASE>" has been upgraded

Prevention

  • Pin chart versions in requirements.yaml and test upgrades in CI with --dry-run.
  • Add {{- if .Values.key }} guards in templates for all optional nested values.
  • Use helm lint in CI to catch nil pointer errors before they reach deploy.
  • Maintain a values.schema.json in the chart to enforce required keys at install time.

Related runbooks

Same stack, same failure family — worth a skim.

ConfigMap not found — pod can't start, volume mount or env failshigh

Pod stuck in CreateContainerConfigError or CrashLoopBackOff

KubernetesFoundation3 causes
Open runbook
MountVolume.SetUp failed — secret not found, pod can't starthigh

Pod stuck in CreateContainerConfigError or CrashLoopBackOff with mount error

KubernetesFoundation3 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.