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".

"tabs are not allowed as indentation"

This error means a line uses a tab character for indentation. YAML only allows spaces for indentation, never tabs. Open the file, replace each leading tab with two spaces, and the parser accepts it. The YAML Validator shows the exact line where the tab appears.

"bad indentation of a mapping entry"

This means a mapping entry is indented inconsently with its siblings — for example a child key sits at the same level as its parent, or a list item is misaligned. Align every key in the mapping to the same column and indent nested values one level (2 spaces) deeper.

"inconsistent indentation"

This happens when some lines use 2 spaces and others use 4 (or a mix of tabs and spaces) within the same block. YAML requires each nesting level to use the same number of spaces. Pick 2 spaces per level and apply it everywhere, then re-validate.

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.