Common YAML Mistakes

YAML's whole pitch is that it's easy to read and write by hand — no braces, no quotes, no trailing commas to chase down. That same lack of punctuation is exactly what makes it easy to write something that parses cleanly into the wrong value without throwing an error at all. Here are the mistakes that actually show up in real files, most of which are silent rather than loud.

First, check whether it's even valid

Before chasing a silent misread, rule out an outright syntax error — paste the file into YAML Validator for the exact line and column. Some of what follows is a hard parse error; the more dangerous half parses fine and just hands your code the wrong value.

1. Tab characters in indentation

The YAML spec forbids tabs for indentation outright — not a style nit, a parse error the moment one appears:

a:
	b: 1

Some editors insert a tab on Enter inside an indented block without it being visually obvious. If a file that looks correctly indented still fails to parse, check for a stray tab first.

2. A colon-space inside an unquoted value

YAML reads : (colon followed by a space) as the marker that starts a nested mapping — including one accidentally embedded inside a value you meant as plain text:

note: Contact: call me

That's a parse error ("nested mappings are not allowed in compact mappings"), not a silent misread — YAML has no way to tell that second colon was supposed to be part of the sentence. Quote the whole value to fix it: note: "Contact: call me".

3. Leading zeros (and trailing zeros) silently disappearing

An unquoted value that looks like a number gets parsed as one — including when the leading or trailing zeros were meaningful:

zip: 00501
version: 1.10

00501 becomes the number 501, and 1.10 becomes 1.1 — both silently, no warning. Zip codes, phone number prefixes, and dotted version strings all need explicit quotes if any digit in them is meaningful on its own: zip: "00501", version: "1.10".

4. Forgetting to quote a value that starts with a reserved character

A handful of characters have special meaning only when they open a plain scalar, which makes the bug easy to miss until that exact value shows up: * (alias), & (anchor), ! (tag), - and ? and : (block indicators), # (comment), | and > (block scalars), @ and ` and % (reserved outright), plus [ and { (flow collections). Two that bite especially often because they fail silently instead of erroring:

tag: &featured
category: [urgent, review]

The first line doesn't produce the string "&featured" — it defines an anchor named featured pointing at nothing, so tag ends up null. The second doesn't produce the literal text "[urgent, review]" — it's parsed as an actual two-item list. Quote the value if you meant it as plain text.

5. An empty value becomes null, not an empty string

description:
description: ""

The first line is null; only the second is an empty string. Code that checks if (value === "") will miss the first form entirely — check for null/undefined too, or write the explicit empty string if that's what you mean.

6. Duplicate keys

role: Engineer role: Manager — legal in some lenient parsers, rejected outright by others, and which value "wins" when it isn't rejected is inconsistent across tools. Don't rely on either behavior; treat a duplicate key as a bug to fix, not a way to override a value.

7. Mixing up the block scalar styles

| and > both start a multi-line string, and confusing them changes your string's content, not just its formatting:

literal: |
  line one
  line two
folded: >
  line one
  line two

literal keeps the newline between the two lines ("line one\nline two\n") — use it for anything where line breaks matter, like a shell script. folded joins them with a single space instead ("line one line two\n") — meant for a paragraph that's wrapped in the source file but should read as one continuous line.

8. The Norway problem

An unquoted yes, no, on, off, or a country code like NO reads as a boolean under YAML 1.1 but as a plain string under 1.2 — the same six characters, two different types, depending entirely on which parser opened the file. Quote anything that looks like one of these regardless of which schema you're on. Full details in What Is YAML?

Try it yourself

YAML Validator catches the hard errors (tabs, the colon-space trap, duplicate keys) and flags the Norway-problem ambiguity — but the silent-misread mistakes above (leading zeros, reserved first characters, empty vs. null) require reading the parsed output, not just checking that parsing succeeded. Once a file is valid, YAML Formatter re-indents it to a consistent width with comments preserved. Both run entirely in your browser.