Skip to main content
DevOps Insightsguides & answers

Helm · troubleshooting

Error: YAML parse error on a Helm chart template

A Helm template rendered text that is not valid YAML, usually because of toYaml indentation or an unquoted value. The line number counts rendered lines, not template lines, so render with --debug and look there.

Reproduced on Helm 3.18.2, . Where the text says “reproduced”, the behaviour was run on that version, not taken from documentation.

First published

New to this? Read what is actually happening first, then come back to the steps.

On this page · 9 sections

Before you start

  • The chart directory, and the same values files and --set flags as the failing command.

Run this first

step 1 of 2
helm template RELEASE . -s templates/FILE.yaml --debug

Look for Line N of the rendered output, counting from the first line after # Source:

Renders one template and, with --debug, prints the rendered YAML even when it does not parse.

Work out which cause you have

A few questions to narrow the list. Every answer ends in a command that confirms or rules the cause out — this cannot see your cluster, so nothing here is a certainty until you have checked.

Narrow it down

0 answered · nothing is sent anywhere

What does the end of the error say?

Cause space

3 of 3 still possible

  • toYaml output indented wronglyCommon
  • A value with a colon, #, or leading special character is not quotedCommon
  • A tab character in a templateOccasional

Nothing ruled out yet. Answer the question above and the branches your answer eliminates will strike through here.

Check it with a tool

Or diagnose it manually

In this order. The first command usually contains the whole answer.

  1. Step 1

    helm template RELEASE . -s templates/FILE.yaml --debug

    Renders one template and, with --debug, prints the rendered YAML even when it does not parse.

    Look for Line N of the rendered output, counting from the first line after # Source:

  2. Step 2

    helm lint .

    Parses every template with the default values.

    Look for [ERROR] lines naming a template

Every cause, and how to fix it

Ordered by how often each one turns out to be the answer.

toYaml output indented wrongly

Common

toYaml returns several lines. indent only indents them, so text before the call shifts the first line; the error appears once the value has more than one line.

Confirm

helm template RELEASE . -s templates/FILE.yaml --debug

The first line of the block further right than the rest, or the block at the wrong level

Fix

  • Put the call at the start of its line with a dash and nindent: {{- toYaml .Values.podLabels | nindent 4 }}, with 4 being the indentation the block needs.
  labels:
    {{- toYaml .Values.podLabels | nindent 4 }}

Reproduced on Helm 3.18.2: rendered both labels under labels:.

A value with a colon, #, or leading special character is not quoted

Common

A value like echo a: b or a string starting with * or { becomes YAML syntax once inserted.

Confirm

helm template RELEASE . -s templates/FILE.yaml --debug

The rendered line containing an extra : or #

Fix

  • Pipe the value through quote: {{ .Values.cmd | quote }}.

A tab character in a template

Occasional

YAML does not allow tabs for indentation. Editors and copied snippets add them.

Confirm

grep -nP '\t' templates/*.yaml

Any line printed

Fix

  • Replace tabs with spaces, and set the editor to insert spaces in YAML files.

Understanding it properly

Skip this if you are mid-incident — the working part of the page is above. Worth reading afterwards, because understanding the mechanism is what stops the next one.

In plain terms

Helm first fills in your templates, then reads the result as YAML. This error means the filled-in result is broken: usually indentation from toYaml, or a value with a colon in it that was not quoted. The fastest way to the fix is to look at what Helm actually produced, not at the template.

Words used on this page

Rendered output
The YAML Helm produces after filling in the templates; this is what is parsed, and what the line number refers to.
nindent N
Starts a new line and indents every line of the value by N spaces; the usual partner of toYaml.
What is actually happening

Reproduced on 23 October 2026 with Helm 3.18.2 and helm template, which needs no cluster. The error names the template file but counts lines in the rendered file: an unquoted value at template line 10 was reported as line 8, because two template-only lines produced no output.

The same template can pass and then fail. With {{ toYaml .Values.podLabels | indent 4 }} written after four spaces, one label rendered as valid YAML; adding a second gave did not find expected key. A value such as echo a: b without quote gave mapping values are not allowed in this context, and a tab gave found character that cannot start any token.

Some indentation mistakes do not fail at all. nindent 2 under labels: rendered labels as empty and put the labels themselves into metadata, and helm template and helm lint both exited 0. Read the rendered output whenever labels or settings do not show up.

How to tell this is your problem
WhereWhat you see
helm install, upgrade or templateError: YAML parse error on CHART/templates/FILE.yaml: error converting YAML to JSON: yaml: line N: did not find expected key
helm lint[ERROR] templates/FILE.yaml: unable to parse YAML: error converting YAML to JSON: …

How to know it is actually fixed

  • helm template exits 0, and the rendered output has every expected field at the right level.

Stopping it happening again

  • Run helm lint and helm template in CI with each values file you deploy with, not only the defaults.
  • Always pair toYaml with nindent at the start of the line, and quote string values.

Sources

Behaviour described here is drawn from official documentation. Where a figure could not be confirmed on an official page it is attributed in the text rather than stated as canonical.

Did this get you to an answer?

No text box on purpose — please do not paste production logs anywhere

Something wrong or out of date? Report it

Where to go next