How to Fix Common YAML Errors (Indentation, Tabs, and More)

YAML's clean syntax comes at a price: it's strict about whitespace and quietly opinionated about types. Here are the errors you'll actually hit, what they mean, and how to fix them fast.

1. Bad indentation

This is the number-one YAML error. YAML uses indentation to express structure, so every level must be consistent.

database:
  host: localhost
   port: 5432   # ← one extra space — breaks the file

Fix: Make every key at the same level use the exact same indentation. Pick 2 spaces and never deviate. Most editors can show whitespace characters — turn that on when debugging.

2. Tab characters

YAML does not allow tabs for indentation. Ever. The catch is that a tab and a few spaces can look identical in your editor.

server:
	port: 8080   # ← this is a TAB, and it will fail

Fix: Replace all tabs with spaces. In VS Code, run "Convert Indentation to Spaces" from the command palette, and set "editor.insertSpaces": true so it never happens again.

3. Unquoted special characters

A value containing :, #, {, }, [, or ] can confuse the parser because those characters have meaning in YAML.

time: 10:30        # ← parsed as a weird sexagesimal number, not "10:30"
url: http://x.com  # ← the colon is ambiguous

Fix: Wrap the value in quotes.

time: "10:30"
url: "http://x.com"

4. The Norway problem (implicit booleans)

YAML coerces yes, no, true, false, on, and off into booleans. The classic bug: the country code for Norway, NO, becomes false.

countries:
  - NO   # ← becomes the boolean false!
  - SE

Fix: Quote any string that could be read as a boolean: "NO".

5. Version numbers losing precision

1.10 looks like a string to you but a float to YAML — and 1.10 as a float is 1.1.

version: 1.10   # ← becomes 1.1

Fix: Always quote version strings: version: "1.10".

6. Duplicate keys

The same key twice at the same level is invalid. Many parsers silently keep the last one, which causes baffling bugs.

config:
  timeout: 30
  timeout: 60   # ← silently overrides the first

Fix: Remove or rename the duplicate.

7. Unclosed quotes and blocks

A string that opens with " but never closes will swallow the rest of the file.

message: "hello
next: value   # ← all consumed by the unterminated string

Fix: Close the quote, or use a block scalar (| or >) for multi-line text.

The fastest way to debug YAML

Reading parser stack traces is miserable. Paste your file into the YAML validator — it pinpoints the exact line and column, names the problem in plain English, and gives you the fix. It catches every error above and more.

Prevention checklist

• Use 2 spaces, never tabs.
• Quote anything ambiguous: versions, country codes, times, URLs, on/off words.
• Turn on "render whitespace" in your editor.
• Validate before committing.

Follow those four rules and you'll avoid 95% of YAML pain.