Debug YAML Indentation and Whitespace Issues

YAML and Whitespace: A Strict Relationship

YAML is perhaps the most whitespace-sensitive format in common use. Unlike most languages where indentation is stylistic, YAML uses indentation as its core structural mechanism. This makes it extremely vulnerable to invisible character problems.

YAML's Whitespace Rules

• Indentation must use spaces only — tabs are explicitly forbidden by the YAML spec
• Consistent indentation depth within a mapping or sequence
• No trailing whitespace — while technically allowed, it can cause unexpected parsing
• Line endings should be consistent (LF preferred)

Common YAML Whitespace Bugs

1. Tab Characters in Indentation

server:
  host: localhost
\tport: 8080    # Tab character! YAML parser error

Error: found character '\t' that cannot start any token

2. Non-Breaking Spaces

database:
  host: localhost    # NBSP after colon instead of space

The NBSP causes the value to include a non-standard space or the parser to fail entirely.

3. Mixed Indentation Depth

services:
  web:
    image: nginx
     port: 80        # 5 spaces instead of 4 — hard to see!

This creates a different nesting level than intended.

4. Trailing Spaces Creating Empty Values

key: \u00B7\u00B7\u00B7    # Trailing spaces make this "   " not empty

Debugging with the Visualizer

1. Copy your YAML content and paste it into the Whitespace Visualizer.
2. Enable Space, Tab, and NBSP toggles.
3. Scan the left margin: you should see only blue dots (·) for indentation, never arrows (→) or degree signs (°).
4. Check that indentation is consistent — count the dots at each level.
5. Clean any tabs or NBSPs found, then copy the fixed YAML.

The YAML Formatter can then validate and reformat the cleaned YAML.