Common YAML errors
Paste the YAML error message you were given into your browser's find bar. Each entry explains what the parser was really objecting to and what to change.
Error message lookup
Parser messages, roughly as they appear, with what actually causes them. Messages vary slightly between libraries; search for the distinctive phrase.
found character '\t' that cannot start any token
A tab in the indentation. YAML forbids tabs there. Convert to spaces:
grep -Pn '\t' file.yaml finds them. Tabs inside a quoted string are fine.
bad indentation of a mapping entry
Two keys in the same mapping start at different columns, or a key is indented under a scalar value that cannot have children. Look at the reported line and the one above it, and count spaces.
could not find expected ':'
Most often an unquoted value containing a colon followed by a space, such as
msg: Error: failed. Quote the whole value. Also produced by a line that
should have been a list item but is missing its hyphen.
mapping values are not allowed in this context
A colon appeared inside a plain scalar. Same cause and same fix as above: quote it. Also seen when a value is indented at the same level as its key.
duplicated mapping key
The same key twice in one mapping. Usually the residue of a bad merge — search the file for the key name and delete the one you do not want.
unexpected end of the stream within a double quoted scalar
A quote opened and never closed. The reported line is the end of the file, not the mistake. Search backwards from there for a line with an odd number of quotes.
could not determine a constructor for the tag
The document contains an explicit tag such as !Ref or
!!python/object that your parser does not know. CloudFormation and some
frameworks define custom tags; you need the matching loader. If the tag is a
!!python/ one and you did not write the file, stop — that is a code
execution attempt, not a config file.
expected a single document in the stream
The file contains --- separators and you called a single-document load
function. Use safe_load_all in Python or loadAll in js-yaml.
while scanning an alias, did not find expected alphabetic or numeric character
A * or & at the start of an unquoted value, where YAML
expects an anchor name. Glob patterns such as path: *.log hit this. Quote
the value: path: "*.log".
block sequence entries are not allowed in this context
A hyphen list appears where the parser is expecting a scalar or a mapping value — typically a list nested directly under another list item without a key.
The failures that produce no error
Some YAML mistakes parse successfully and mean the wrong thing. No validator will flag them, so they are worth committing to memory.
| Written | Parsed as | Fix |
|---|---|---|
country: NO | false | "NO" |
enabled: yes | true (YAML 1.1) | Use true explicitly |
version: 1.10 | 1.1 | "1.10" |
zip: 07030 | 3608 (octal, YAML 1.1) | "07030" |
build: 1e5 | 100000.0 | "1e5" |
at: 12:30 | 750 (sexagesimal, YAML 1.1) | "12:30" |
name: with nothing after | null, not "" | name: "" |
| Key indented one space too far | A child of the previous key | Re-align |
The pattern is consistent: unquoted scalars are inspected and converted. If a value is meant to be a string and could be read as a number, a boolean, or a date, put quotes around it. Quoting a value that did not need them costs nothing.
A debugging order that works
- Check for tabs first. It takes one grep and it is the most common cause, and the indentation rules explain why.
- Paste the file into the YAML validator and read the line and column.
- If it parses, read the normalised output rather than your source. Structural bugs show up there immediately — a key nested where you did not expect it.
- If the structure is right but a value is wrong, look for a missing quote. Running the file through YAML to JSON makes wrong types obvious, because JSON shows them without inference.
- Still stuck? Delete half the file and try again. Binary search finds the bad line in a few iterations.