Helm "YAML parse error on ... template" - Fix Template Output in CI

By Kaveh Alemi·Latchkey

Helm rendered a template and the resulting text is not valid YAML. The Go templating produced broken indentation, an empty value where a key was expected, or an unquoted interpolated string that corrupts the document.

What this error means

helm install/template fails with Error: YAML parse error on <chart>/templates/<file>.yaml: error converting YAML to JSON: yaml: line N: <detail>. The chart’s logic is fine; the rendered output at that line is malformed.

helm output

Error: YAML parse error on api/templates/deployment.yaml: error converting YAML
to JSON: yaml: line 23: did not find expected key

Diagnose it: render the chart before you install it

Most Helm failures are visible in the rendered manifests. Template them locally with the same values CI uses and you will usually see the problem without touching the cluster.

Terminal

# what will actually be applied
helm template <release> <chart> -f values.ci.yaml | head -60

# validate against the live cluster schema without installing
helm install <release> <chart> -f values.ci.yaml --dry-run --debug

# what state is the release actually in?
helm history <release>
helm status <release>

Common causes

Bad indentation from templating

A {{ .Values.x | nindent N }} with the wrong N, or a block inserted at the wrong indentation, shifts keys so the rendered YAML no longer parses.

Missing/empty value or unquoted interpolation

A value that renders empty leaves key: with nothing (or wrong structure), and an unquoted string containing : or special chars breaks the document. Numbers/strings often need | quote.

How to fix it

Render the template and read line N

See exactly what Helm produced at the failing line so you can spot the indentation or empty value.

Terminal

helm template ./chart --debug 2>&1 | sed -n '18,28p'
# or render one file
helm template ./chart --show-only templates/deployment.yaml

Fix indentation and quote values

Use nindent/indent with the correct column for inserted blocks.
Quote interpolated scalars ({{ .Values.x | quote }}) and provide defaults ({{ .Values.x | default "..." }}) so nothing renders empty.
Lint the chart (helm lint) and validate rendered output before install.

How to prevent it

Run helm lint and helm template in CI to catch render errors before install.
Quote interpolated values and supply defaults so templates never emit empty keys.
Use nindent carefully and review rendered output for indentation drift.

Frequently asked questions

What causes Helm "YAML parse error on ... template"?

There are 2 common causes: bad indentation from templating and missing/empty value or unquoted interpolation. A {{ .Values.x | nindent N }} with the wrong N, or a block inserted at the wrong indentation, shifts keys so the rendered YAML no longer parses.

How do I fix Helm "YAML parse error on ... template"?

There are 2 fixes depending on which cause you have: render the template and read line n and fix indentation and quote values. Work through them in order, since the first is the most common.

What does Helm "YAML parse error on ... template" actually mean?

helm install/template fails with Error: YAML parse error on <chart>/templates/<file>.yaml: error converting YAML to JSON: yaml: line N: <detail>.

How do I stop Helm "YAML parse error on ... template" happening again?

Run helm lint and helm template in CI to catch render errors before install. The prevention section lists 3 changes that keep it from recurring.