Common YAML Errors and How to Fix Them
YAML error messages have a reputation for being cryptic, but most of them boil down to a handful of repeat offenders. Here's what they actually mean in plain English.
"mapping values are not allowed here"
This almost always means there's a colon somewhere it isn't expected — usually an unquoted value that contains a colon, like a time or a URL.
# breaks
event_time: 10:45
# fixed
event_time: "10:45""bad indentation of a mapping entry"
Two sibling keys aren't lined up at the same column. This is almost always a stray extra space from copy-pasting between editors with different tab settings.
# breaks — "port" is indented one space further than "host"
server:
host: localhost
port: 8080
# fixed
server:
host: localhost
port: 8080"found character that cannot start any token"
Usually a tab character where a space was expected, or a stray special character like @, `, or % at the start of a line without quotes around it.
"duplicate key"
The same key appears twice at the same level. YAML allows it technically in some parsers (the last one silently wins), but strict parsers — and our validator — will flag it, because it's almost never intentional.
"end of document not expected"
This one usually means an indentation level dropped unexpectedly partway through a block, effectively closing a section earlier than you meant to.
The fastest way to actually find these
Reading a long YAML file line by line to spot a whitespace issue is slow and error-prone. Pasting the whole thing into the validator gives you the exact line and column instead of a guess, which usually turns a ten-minute hunt into a five-second fix. If the error keeps recurring in files you write by hand, it's worth reading our indentation rules guide once properly — it clears up 80% of these for good.