Skip to main content
DevOps Insightsguides & answers

YAML · troubleshooting

yaml: found character that cannot start any token

The parser met a character YAML does not allow there: almost always a tab used for indentation, or an unquoted value starting with @ or a backtick.

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 · 8 sections

Before you start

  • The file, and a way to see invisible characters.

Run this first

step 1 of 1
cat -et FILE | grep -n '\^I'

Look for ^I at the start of a line

Shows tabs as ^I with line numbers (use cat -A on Linux).

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

Does the message include a line number?

Cause space

2 of 2 still possible

  • A tab used for indentationCommon
  • An unquoted value starting with @ or a backtickCommon

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

Or diagnose it manually

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

  1. Step 1

    cat -et FILE | grep -n '\^I'

    Shows tabs as ^I with line numbers (use cat -A on Linux).

    Look for ^I at the start of a line

Every cause, and how to fix it

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

A tab used for indentation

Common

Pasted from a terminal, a web page or an editor set to indent with tabs. It looks identical to spaces.

Confirm

grep -n "$(printf '\t')" FILE

Any line printed: it contains a tab (cat -et FILE shows it as ^I)

Fix

  • Replace tabs with spaces: expand -t 2 FILE > FILE.new && mv FILE.new FILE, or set the editor to indent YAML with spaces.

An unquoted value starting with @ or a backtick

Common

Usernames, npm scopes such as @org/package, decorators or shell command substitution written as values.

Confirm

grep -nE ':[[:space:]]+[@`]' FILE

A value that begins with @ or a backtick

Fix

  • Quote the value: user: "@admin".

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

YAML indents with spaces only; a tab, which most editors display exactly like spaces, is not allowed there. A few characters, @ and the backtick, are reserved and cannot start an unquoted value. Either one stops the parser before it reads a single key.

Words used on this page

Token
The smallest piece the parser reads: a key, a value, a dash, a colon.
Reserved indicator
A character the YAML specification sets aside for future use: @ and the backtick.
What is actually happening

Reproduced with Helm 3.18.2: a tab before repository: printed yaml: line 2: found character that cannot start any token. The YAML 1.2.2 specification says tab characters must not be used in indentation.

An unquoted value starting with @ (user: @admin) or a backtick (cmd: date) printed the same message, without a line number. The specification reserves both characters for future use.

cat -et on macOS and cat -A on Linux both show a tab as ^I, which makes it visible.

How to tell this is your problem
WhereWhat you see
helm and other Kubernetes toolsyaml: line N: found character that cannot start any token
Reserved character, no line numberyaml: found character that cannot start any token

How to know it is actually fixed

  • The file parses, and grep for a tab character prints nothing.

Stopping it happening again

  • Add an .editorconfig with indent_style = space for *.yaml and *.yml.
  • Quote values that start with anything other than a letter or digit.

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