YAML Error Found Character That Cannot Start Any Token
Which characters trigger this scanner error, a tab, at sign, backtick or percent sign, what each looks like in output and the fix that clears it.
"Found character that cannot start any token" sounds like noise, and it is precise. The scanner, the first stage of the parser, reads characters and groups them into tokens, and at some position it met a character that cannot begin any kind of token in that position. Two situations produce it in nearly every real case: a plain value that starts with a reserved character, and a tab. This post lists the characters, shows the line and column the parser reports, and covers the look-alikes that do not fail but should worry you more.
What "token" means here
The YAML scanner turns the text into tokens: keys, values, block starts and ends, scalars, anchors, tags, flow brackets. A plain scalar, an unquoted value, may start with most characters but not with a handful that YAML reserves for its own syntax. If the character at the start of a scalar is one of the reserved ones and does not form a valid token of its own, the scanner stops with this message. The message names the character and the position.
The characters, tested
| Document | Result |
|---|---|
token: @abc | found character '@' that cannot start any token, line 1, column 8 |
`cmd: date ` | found character '`' that cannot start any token, line 1, column 6 |
pct: %value | found character '%' that cannot start any token, line 1, column 6 |
a: then a tab then 1 | found character '\t' that cannot start any token, line 1, column 3 |
a: newline, tab, b: 1 | found character '\t' that cannot start any token, line 2, column 1 |
The at sign and the backtick are reserved by the specification for future use, which means no valid YAML document may start a plain scalar with them. The percent sign at the start of a line starts a directive, and in a value it is not allowed as the first character. The tab is not allowed as indentation, and the example shows it is not allowed as the separator after a colon either, which I would not have guessed.
The reported position is the character itself. For token: @abc the at sign is the eighth character, and the message says so. The same document read by yq gives the same message with the position in its own format (L1.C8). Because the position is exact, this error is easy to fix once you find the character, which is the main difficulty when the character is a tab.
Fix 1: quote the value
For the reserved starting characters, quoting is the whole fix:
token: "@abc"
cmd: '`date`'
pct: "%value"All three load as strings. Typical real-world sources of the problem: a package name with a scope (@angular/core), a shell command copied into a field, a template placeholder (%{name}), a percentage written first (%complete). In CI and package manifests, scoped npm package names are the most common cause by far. Quote the string, and the file loads.
If the value is in a flow collection, quote it there too: deps: ["@angular/core", "rxjs"].
Fix 2: replace tabs with spaces
A tab is never valid as indentation, and the parser also refuses it after a colon. The message gives the position, and the position is the problem: you cannot see a tab. In most editors it looks like some spaces. Make it visible: turn on rendering of whitespace characters, or use the shell:
grep -nP '\t' file.yaml
cat -A file.yaml | sed -n 3pt1.yaml:3: - run: build
^I- run: build$The first command prints the lines that contain a tab, and cat -A shows tabs as ^I and line ends as $. Replace them with spaces and set your editor to insert spaces for the Tab key. To find every file in a tree with a leading tab: grep -rlP '^\s*\t' . (finding tab characters hiding in a YAML file has the options, including a one-line fix with expand). yamllint reports the same condition as a syntax error with the line and column, which makes it a good CI check.
Fix 3: remove characters pasted from elsewhere
When a file has been copied from a web page, a chat window or a document, the offending character is often an invisible or lookalike one. The test shows that the situation is more nuanced than "the parser rejects odd characters":
| Document | Result |
|---|---|
| Smart double quotes around a word | loaded; the quotes became part of the string |
| A stray closing bracket at the end of a value | loaded as part of the string |
| A pipe in the middle of a value | loaded as part of the string |
| A zero-width space after the colon | loaded; the value became the string a:\u200b 1, not a mapping |
| A byte order mark at the start of the file | loaded without error |
| Non-breaking spaces as indentation | loaded without error |
Most of these do not raise any error. The parser accepts them as ordinary characters, which means the data is wrong and no tool complains. The non-breaking space case is the worst: two non-breaking spaces used as indentation produced {'a': None, '\xa0\xa0b': 1}, a key whose name is two invisible characters and b. Your program looks for b and does not find it. The zero-width space after the colon turned a whole line into one string: 'a:\u200b 1'.
To look for these, search for non-ASCII characters in files that should not have them: grep -nP '[^\x00-\x7F]' file.yaml prints any line with a character outside ASCII, which in an English configuration file is nearly always a mistake. Then decide whether each is legitimate (a real accented letter in a string) or damage (a non-breaking space, a smart quote). Linters can enforce an ASCII policy, and an editor setting that highlights unusual whitespace shows them.
A checklist for this error
Read the line and column. The character is there.
If it is
@, a backtick or%at the start of a value, quote the value.If it is
\t, replace tabs with spaces in the whole file, not just on that line.If you cannot see anything wrong, print the line with
cat -Aor show invisible characters in the editor.After fixing, load the file and print the result. Check the keys are the ones you expect, especially if the file was pasted from somewhere.
Add
yamllintto CI so the next occurrence fails on the pull request.
Related reading
The cluster hub is fixing YAML errors that make no sense. The sibling errors are mapping values are not allowed here, did not find expected key and fixing special characters that break YAML values. The reserved indicators are listed in section 5.3 of the YAML 1.2.2 specification, and the tab rule in the indentation section. Reformat a corrected file in the YAML formatter.
When the offending character is invisible
It is a non-breaking space or a zero-width character. These usually load without an error and break the meaning. Search for non-ASCII characters, and normalize the file.
The editor hides tabs. Turn on visible whitespace for the file type. A tab that displays as eight spaces is still a tab.
The file came through a converter. Word processors, chat tools and some web editors replace quotes and hyphens with typographic versions. Paste into a plain-text editor first.
The error names a character that is not in your file. Check the encoding. A file saved in a different encoding can produce stray bytes that decode into characters you did not type.
