How to fix: Tabs in YAML cause cryptic parse errors

YAML strictly forbids tab characters for indentation. Only spaces are allowed. Most editors default to tabs, and the error message does not clearly say 'you used a tab'. Fix: 1. Configure your editor to use spaces (not tabs) for YAML files. 2. Use the Diff Checker to compare your file against a known-good version. 3. Run cat -A file.yaml - tabs appear as ^I. 4. In VS Code: open the file and check the status bar for 'Spaces: 2'.

How to fix: Wrong indentation silently restructures data

YAML uses indentation to define structure. A single misaligned space can move a property from one object to another. Unlike JSON (which uses braces), YAML gives no clear visual boundaries. Fix: 1. Convert YAML to JSON with a YAML-to-JSON converter to see the actual structure. 2. Validate the parsed output against your schema using the JSON Formatter. 3. Use the Diff Checker to compare expected vs actual structure. 4. Use consistent 2-space indentation and enable editor guides.

How to fix: Special characters in values cause parse errors

Colons, hashes, brackets, and other characters have special meaning in YAML. Unquoted values containing :, #, {, [, &, * cause parsing ambiguity or errors. Fix: 1. Quote values containing special characters: "value: with colon". 2. Use double quotes for values with # (otherwise treated as comment). 3. Use the Regex Tester to find unquoted special chars. 4. When in doubt, quote it - quoted strings are always safe in YAML.

Data Formats 2026-04-20

YAML Parsing Mistakes and Solutions

Fix YAML parsing errors: indentation issues, type coercion surprises, multiline strings, special characters, and the Norway problem. Complete debugging guide.

{ } JSON Formatter Free ± Text Diff Checker Free .* Regex Tester Free

YAML parsing errors YAML indentation error YAML common mistakes fix YAML syntax YAML debugging YAML type coercion

The Problem

YAML silently interprets data in unexpected ways: 'no' becomes false, '1.0' becomes a float, tabs cause cryptic errors, and indentation mistakes restructure your entire configuration without any warning.

YAML was designed to be human-friendly, but its flexibility hides sharp edges. Invisible indentation errors, surprising type coercions, and the infamous Norway problem have caused production outages at companies of every size. This guide covers the 5 most treacherous YAML parsing mistakes and shows you how to catch them before they reach production.

Common errors covered

1 Tabs in YAML cause cryptic parse errors
2 Strings silently become booleans or numbers (the Norway problem)
3 Wrong indentation silently restructures data
4 Multiline strings have unexpected whitespace or newlines
5 Special characters in values cause parse errors

Tabs in YAML cause cryptic parse errors

Error message

yaml.scanner.ScannerError: while scanning for the next token
found character '\t' that cannot start any token

Root cause

YAML strictly forbids tab characters for indentation. Only spaces are allowed. Most editors default to tabs, and the error message does not clearly say 'you used a tab'.

Step-by-step fix

1 Configure your editor to use spaces (not tabs) for YAML files.
2 Use the Diff Checker to compare your file against a known-good version.
3 Run cat -A file.yaml - tabs appear as ^I.
4 In VS Code: open the file and check the status bar for 'Spaces: 2'.

Wrong

# YAML with tabs (invisible but fatal):
server:
	host: localhost    # TAB character - parse error!
	port: 8080

Correct

# YAML with spaces only:
server:
  host: localhost    # 2 spaces - correct
  port: 8080

Strings silently become booleans or numbers (the Norway problem)

Error message

(No error - data has wrong type)
country: NO  becomes boolean false
version: 1.0 becomes float 1.0
port: 080    becomes integer 80 (or octal 64)

Root cause

YAML auto-detects types. yes, no, on, off, true, false become booleans. Numbers with leading zeros may be interpreted as octal. This is the infamous 'Norway problem' (country code NO = false).

Step-by-step fix

1 Always quote strings that could be misinterpreted: "NO", "1.0", "080".
2 Validate parsed output with the JSON Formatter - convert YAML to JSON to see actual types.
3 Use YAML 1.2 which reduces boolean values to only true/false.
4 Add schema validation to catch type mismatches in CI/CD.

Wrong

countries:
  - NO      # boolean false, not Norway!
  - GB      # string (happens to work)
version: 1.0   # float, not string '1.0'
port: 080      # octal 64 or int 80

Correct

countries:
  - "NO"    # quoted - stays string
  - "GB"    # consistent quoting
version: "1.0"  # quoted - stays string
port: "080"     # quoted - stays string

Wrong indentation silently restructures data

Error message

(No error - data structure is different than intended)
Nested object becomes a sibling, or value becomes a key

Root cause

YAML uses indentation to define structure. A single misaligned space can move a property from one object to another. Unlike JSON (which uses braces), YAML gives no clear visual boundaries.

Step-by-step fix

1 Convert YAML to JSON with a YAML-to-JSON converter to see the actual structure.
2 Validate the parsed output against your schema using the JSON Formatter.
3 Use the Diff Checker to compare expected vs actual structure.
4 Use consistent 2-space indentation and enable editor guides.

Wrong

database:
  host: localhost
  port: 5432
 credentials:        # Wrong! Same level as 'database'
   user: admin
   password: secret

Correct

database:
  host: localhost
  port: 5432
  credentials:       # Correct! 2-space indent - child of 'database'
    user: admin
    password: secret

Multiline strings have unexpected whitespace or newlines

Error message

(No error - string contains unexpected leading spaces or trailing newlines)

Root cause

YAML has multiple multiline string modes: | (literal), > (folded), |- (literal, strip final newline), >- (folded, strip). Each behaves differently with indentation and newlines.

Step-by-step fix

1 Use | for preserving newlines (scripts, code blocks).
2 Use > for wrapping long text into a single line.
3 Add - suffix to strip the trailing newline: |- or >-.
4 Test the output with the Diff Checker to verify exact whitespace.

Wrong

# Trailing newline surprise:
script: |
  echo hello
  echo world
# script value is 'echo hello\necho world\n' - note trailing newline

Correct

# Strip trailing newline with |-
script: |-
  echo hello
  echo world
# script value is 'echo hello\necho world' - no trailing newline

Special characters in values cause parse errors

Error message

yaml.scanner.ScannerError: mapping values are not allowed here
yaml.parser.ParserError: expected block end, but found scalar

Root cause

Colons, hashes, brackets, and other characters have special meaning in YAML. Unquoted values containing :, #, {, [, &, * cause parsing ambiguity or errors.

Step-by-step fix

1 Quote values containing special characters: "value: with colon".
2 Use double quotes for values with # (otherwise treated as comment).
3 Use the Regex Tester to find unquoted special chars.
4 When in doubt, quote it - quoted strings are always safe in YAML.

Wrong

url: https://example.com  # YAML error - colon triggers mapping
comment: Fix this # TODO  # everything after # is a comment
pattern: [a-z]+          # parsed as YAML array, not regex

Correct

url: "https://example.com"      # quoted - safe
comment: "Fix this # TODO"       # quoted - # is literal
pattern: "[a-z]+"               # quoted - not a YAML array

Debugging Approach

1 Convert YAML to JSON to see the actual parsed structure and types.
2 Check for invisible tabs: run 'cat -A file.yaml' in terminal.
3 Validate against your expected schema - check both structure and types.
4 Use Diff Checker to compare the parsed output against expected output.
5 Test with known-tricky values: NO, yes, 1.0, 080, and strings with colons.

Prevention Checklist

Configure your editor to use spaces (never tabs) for YAML files.
Always quote strings that look like booleans or numbers: "NO", "1.0", "080".
Use YAML 1.2 parsers which only recognize true/false as booleans.
Validate YAML against a JSON Schema in your CI/CD pipeline.
Use |- or >- for multiline strings to avoid trailing newline surprises.
Quote any value containing :, #, {, [, or &.

Frequently Asked Questions

Should I use YAML or JSON for configuration files?

JSON is safer (no type coercion, strict syntax) but harder to read for humans. YAML is more readable but has more gotchas. For machine-generated config, use JSON. For human-edited config (Docker Compose, Kubernetes), use YAML with strict validation and always quote ambiguous values.

What is the Norway problem in YAML?

In YAML 1.1, the country code NO (Norway) is interpreted as boolean false. Similarly, YES, ON, OFF are all booleans. YAML 1.2 fixed this by only recognizing true/false, but many parsers still default to YAML 1.1 behavior.

How do I include a literal colon in a YAML value?

Quote the entire value: message: "Error: file not found". Without quotes, YAML interprets the colon as a key-value separator. Double quotes also let you use escape sequences like \n.