Guide

Common YAML errors and how to fix them

Six mistakes cause almost every failed parse. Here is what each one means — and the exact fix.

By yamltojsonfree · Published August 25, 2026 · Updated September 7, 2026

Why YAML errors are so hard to read

YAML builds structure out of indentation, so when something goes wrong the parser often can’t tell what went wrong — only that the structure stopped making sense. That’s why an unclosed bracket on line 12 is routinely reported as “bad indentation” on line 50: the parser kept consuming lines, looking for a closing delimiter that never came, and only gave up much later.

The errors below are listed by their real cause, not by the message a parser prints. If you’d rather have them diagnosed automatically, paste your document into the YAML validator or the YAML to JSON converter — each of these errors is detected as itself, with the line, a plain-English explanation, and a suggested fix.

The six errors, in full

The six most common YAML syntax errors are: (1) a tab used for indentation, (2) an unquoted value containing a colon, (3) an unclosed bracket, brace, or quote, (4) a duplicate key, (5) an alias to an anchor that does not exist, and (6) sibling keys indented differently.

1. A tab character is used for indentation

Why: YAML forbids tabs for indentation entirely, because their width is ambiguous across editors.

Fix: Replace each tab with spaces — two per level is conventional. Most editors can do this with “convert indentation to spaces”.

2. An unquoted value contains a colon

Why: title: foo: bar is ambiguous — the parser can’t tell which colon separates the key from the value.

Fix: Quote the value: title: 'foo: bar'.

3. A bracket, brace, or quote is never closed

Why: Flow collections such as [80, 443] and quoted strings must be closed on the same logical line. Most parsers report this as an indentation error many lines later.

Fix: Add the closing delimiter, or rewrite the value in block style with one entry per line.

4. The same key appears twice

Why: YAML mappings require unique keys, and so do JSON objects. Silently keeping the last value would hide a real bug.

Fix: Rename or remove the duplicate — or indent it one level deeper if it was meant to be a sub-key.

5. An alias points at an anchor that doesn’t exist

Why: *name refers to an anchor defined with &name. Anchors must appear earlier in the document than the aliases that use them.

Fix: Define the anchor first, and check the spelling — anchor names are case sensitive.

6. Sibling keys are indented differently

Why: Every key in the same block must sit at the same indentation. Two spaces on one line and three on the next ends the block early.

Fix: Make the indentation of all sibling keys identical.

Looking for a specific parser message?

Parsers describe the same six mistakes in different words: kubectl, Helm, Ruby and PyYAML with the C loader speak libyaml’s dialect, pure-Python PyYAML has its own, and js-yaml folds several causes into one message. Each of the messages below has a page of its own with every cause, the fix, and how the line number should be read.

Two fixes, before and after

The two errors people hit most often, shown as broken YAML next to its corrected form.

Unquoted colon in a value

The second colon makes the line ambiguous; quoting the whole value resolves it.

Broken

title: Deploy: production
owner: platform team

Fixed

title: "Deploy: production"
owner: platform team

Uneven sibling indentation

“ports” sits at three spaces while its siblings sit at two, so the block ends early.

Broken

server:
  host: localhost
   ports:
    - 8080

Fixed

server:
  host: localhost
  ports:
    - 8080

When the YAML is valid but still wrong

A document can parse perfectly and still mean something you didn’t intend. The classic case is country: NO, which is valid YAML in every version — but reads as the string "NO" under YAML 1.2 and the boolean false under YAML 1.1. That whole class of silent type change is covered in the YAML 1.1 vs 1.2 guide.

References

YAML 1.2.2 specification— the rules for indentation, flow collections, anchors, and unique keys
YAML 1.2.2 §6.1 Indentation spaces— why tabs are not allowed
PyYAML documentation— the error messages most Python users see
js-yaml— the parser behind the tools on this site

Fix your YAML now

Every error on this page is caught with the exact line and a suggested fix by the free tools on this site. Nothing is uploaded — everything runs in your browser.