Common YAML Errors & How to Fix Them

"mapping values are not allowed here"

YAML hit a colon (:) where it expected a key. Two causes dominate:

• Missing space after a colon — name:api should be name: api.
• An unquoted value with a colon in it — URLs like url: http://example.com confuse the parser. Quote the value: url: "http://example.com".

"did not find expected key" / "expected "

This is almost always indentation. A child line is not indented further than its parent, so YAML cannot place it in the mapping.

# Bad
config:
debug: true

# Good
config:
  debug: true

"found character '\\t' that cannot start any token"

The YAML spec forbids tabs for indentation. A pasted tab is invisible but breaks parsing. Replace tabs with spaces — 2 per level is the common convention.

Duplicate keys

Declaring the same key twice in one mapping is invalid. Some parsers take the last value silently; others throw. Remove the duplicate or rename one.

# Bad
title: First
title: Second

# Good
title: First
subtitle: Second

Boolean and number coercion

Unquoted yes, no, on, off become booleans, and values like 007 become numbers. If you mean the literal string, quote it: version: "007".

Find and fix them fast

Paste your YAML into the YAML Validator for a precise line/column report. For front matter, the Frontmatter Validator & Fixer goes further — it auto-repairs the common mistakes above and shows exactly what changed.

Related guides

• YAML indentation guide — spaces, tabs, and common errors.
• YAML format example — a readable, annotated sample.
• YAML front matter guide — what it is and how to write it.