YAML error
“found character that cannot start any token”
The scanner reached the start of a new token and found a character no YAML token may begin with. In almost every case it is a tab used for indentation. The other two are a value beginning with @ or a backtick, which YAML reserves.
By yamltojsonfree · Published · Updated
What the parser is telling you
YAML indentation must be spaces. A tab at the start of a line is not treated as indentation, so the scanner tries to read it as the start of a value, and no value can start with a tab. The message points at the column of the tab, which most editors render as blank space, so the line looks fine.
Two visible characters trigger the same message: @ and the backtick. The YAML specification reserves both for future use, so a value such as email: @handle must be quoted. A @ later in a value, as in nginx@sha256:..., is fine.
Who prints this message
PyYAML names the character: “found character '\t' that cannot start any token”. libyaml and go-yaml, and therefore kubectl, Helm and Docker Compose, print it without the character.
The causes, with fixes
Broken YAML on the left, the corrected form on the right. The fix under each pair is the one that applies to that cause.
A tab used for indentation
Editors that draw tabs as spaces hide this until the file is opened elsewhere. Copying from a web page, a terminal, or a Makefile is the usual source.
Broken
server:
host: localhostFixed
server:
host: localhostFix: The broken example contains a real tab. Use your editor’s “convert indentation to spaces” command, or expand -t 2 file.yaml.
A value that starts with @
The @ character is reserved at the start of a plain value. Handles, mentions and some image references start with it.
Broken
maintainer: @platform-teamFixed
maintainer: "@platform-team"Fix: Quote it. The same applies to a value starting with a backtick, which often arrives from Markdown.
A tab elsewhere in the line
libyaml and go-yaml accept a tab after the colon, but the pure-Python PyYAML scanner does not, so a file can pass in one tool and fail in another.
Broken
key: valueFixed
key: valueFix: Replace every tab outside quoted strings with spaces and the file behaves the same everywhere.
Find it fast
- 1.Run
grep -nP "\t" file.yamlto list every line containing a tab, orcat -A file.yamlto see tabs as^I. - 2.Turn on “render whitespace” in your editor; tabs and spaces are drawn differently.
- 3.If there are no tabs, look at the reported column for
@or a backtick and quote the value. - 4.Paste the document into the YAML validator on this site; it reports “A tab character is used for indentation” with the line marked.
The same error in other parsers
| Parser | Message |
|---|---|
| PyYAML, pure-Python loader | found character '\t' that cannot start any token |
| libyaml, go-yaml (kubectl, Helm, Compose), Ruby Psych | found character that cannot start any token |
| js-yaml (Node, most browser tools) | tab characters must not be used in indentation |
| yaml (npm) | Tabs are not allowed as indentation |
| This site’s validator | A tab character is used for indentation. |
Frequently asked questions
Are tabs allowed anywhere in YAML?
Inside quoted strings and inside block scalar content, yes. As indentation, never. Between a colon and its value, libyaml and go-yaml accept a tab but pure-Python PyYAML rejects it, so the safe rule is spaces everywhere outside quotes.
My editor shows spaces, so why does the parser see a tab?
Editors draw a tab as a run of blank columns, so a line indented with one tab looks like a line indented with two or four spaces. Only a whitespace-rendering mode, cat -A, or a grep for a literal tab will show the difference.
Why does a Docker image reference fail with this error?
It does not when the @ is in the middle, as in nginx@sha256:abc. The message appears only when @ is the first character of an unquoted value. Quote the value if it must start with @.
Related errors
“control characters are not allowed”
The file contains a byte that YAML forbids anywhere in a document: a control character such as a terminal escape code, a form feed, a NUL byte or DEL. The usual source is coloured command output redirected into a file. Find the byte with grep and delete it.
Read the fix“bad indentation of a mapping entry”
js-yaml reports several unrelated mistakes under this one message: an unquoted value containing a colon, a sibling key indented differently, a key nested under a key that already has a value, or a value starting with @ or a backtick. Check the reported line for each, in that order.
Read the fix“did not find expected key”
The parser was inside a mapping and expected either another key at the same indentation or the end of the block, but found something that cannot be a key: a line dedented by the wrong amount, a list dash, or an invisible character. Line up the indentation of the line it reports with its siblings.
Read the fixAll six underlying mistakes, ordered by cause rather than by message, are in the guide Common YAML errors and how to fix them. Every one of them is caught with the exact line and a suggested fix by the free tools below; nothing is uploaded.
YAML to JSON
Convert YAML into formatted or minified JSON, with errors pinned to the exact line.
OpenJSON to YAML
Turn JSON back into readable YAML, with control over indentation and key order.
OpenYAML Validator
Check YAML for syntax errors and get a plain-English explanation of what went wrong.
OpenYAML Formatter
Reformat messy YAML with consistent indentation and keep your comments intact.
Open