Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 39 ยท YAML and Config Files

YAML Gotchas - The Norway Problem and Other Pitfalls

Learn the YAML pitfalls that break real files - the Norway problem, octal and sexagesimal numbers, version strings, duplicate keys, tabs - and how to write YAML that survives any parser.

YAML is friendly to write and sometimes hostile to read back. Its main design goal was human comfort, so a plain value without quotes is interpreted: the parser guesses a type. The guesses are reasonable most of the time and badly wrong some of the time. Most famous is the Norway problem: the country code NO becoming the boolean false. This lesson lists the traps in the order you are likely to meet them, shows a model resolver that reproduces them, and ends with habits that make your files safe in any parser.

Two YAML versions, two rule sets

The behaviour depends on which version the parser follows.

  • YAML 1.1 (2005) resolves many words as booleans and has octals, hex, sexagesimal numbers and a merge key. PyYAML and many older libraries still follow it, and so do tools built on them (older Ansible, parts of Kubernetes tooling).
  • YAML 1.2 (2009) is much stricter: only true and false are booleans, and numbers follow the JSON-like rules. yaml for JavaScript, ruamel.yaml (configurable) and Go's yaml.v3 are close to 1.2.

You rarely know which one a consumer uses, so write files that mean the same in both.

The Norway problem and other booleans

In YAML 1.1 all of these are booleans: y, Y, yes, Yes, YES, n, N, no, No, NO, true, false, on, off (in any capitalisation).

YAML
countries: [GB, DE, NO]       # NO becomes false in YAML 1.1
answer: yes                   # true in 1.1, the string "yes" in 1.2

The list above loads as ["GB", "DE", false] in a 1.1 parser. The same happens to a CI setting named on: (it becomes the key true in 1.1; GitHub Actions has special handling for this). Fix: quote the value ("NO"), and use only true and false for real booleans.

Numbers that are not what you meant

YAML
zip: 01234        # octal in 1.1 -> 668; a string or number in 1.2 depends
phone: 0800123    # same problem
port: 0o17        # octal in 1.2
time: 12:30       # sexagesimal in 1.1 -> 750 (12*60 + 30)
version: 1.10     # the number 1.1
sci: 1e3          # float 1000 (in 1.1 only 1.0e+3 style is a float)

Zip codes, phone numbers, ids with leading zeros, versions and clock times are strings by nature: they identify, they are not for arithmetic. Always quote them. A version like 3.10 that silently becomes 3.1 has broken many CI matrices (Python 3.10 turned into 3.1).

Also, 0x1F is hexadecimal and .inf, -.inf, .nan are special floats in both versions, while ~ and empty values are null.

Dates become dates

YAML 1.1 also has a timestamp type. released: 2025-03-14 may load as a date object (Python's datetime.date, JavaScript Date in some libraries) instead of a string, and JSON conversion later fails or changes the format. Quote it if you want text.

Node.js A model resolver: YAML 1.1 versus 1.2 core

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The table makes the point: the column for YAML 1.1 holds booleans and odd numbers where 1.2 keeps text. If you must support both, quote.

Indentation and syntax traps

  • Tabs. Not allowed for indentation. Editors that insert tabs silently break files.
  • Duplicate keys. The specification says keys must be unique, but many parsers accept a: 1 followed by a: 2 and keep the last one without an error. That hides copy-paste mistakes; enable your linter's duplicate-key check.
  • Colon in a value. title: Chapter 1: Intro fails because of the second : . Quote the value.
  • Leading special characters. A value starting with *, &, !, %, @ or a backtick must be quoted (glob: "*.js"). Without quotes *.js is read as an alias.
  • Trailing comment confusion. url: http://a.test/#top is fine (no space before #), but note: use # for comments ends the value at the hash.
  • A list item that is a string with a colon. - note: x is a mapping; - "note: x" is a string.
  • Indentation of nested lists. One missing space turns a child into a sibling and the structure changes without any error.
  • Special strings. null, ~, true, no (1.1), 1e3, 0x10: any text that matches a type must be quoted when you mean text.
Node.js A tiny linter for risky plain values

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Habits that make YAML safe

flowchart TD
  A["Write a value"] --> B{"Is it clearly a number you will calculate with, or true/false?"}
  B -- "yes" --> C["leave it plain"]
  B -- "no" --> D["quote it"]
  D --> E["add a YAML linter and a schema check in CI"]
  C --> E

Plain only when you mean a number or boolean; quote every identifier.

  1. Quote strings that are not obviously words: ids, codes, versions, times, anything with a colon or leading symbol.
  2. Use true/false and nothing else for booleans.
  3. Use a linter (such as yamllint) and validate the loaded data against a schema; see Schemas and Validation Tools.
  4. Load with the safe function and load the file in the same language that will consume it.
  5. Keep files small and flat. Deep nesting and many anchors multiply the chances for a wrong indent.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the Norway problem?

    YAML 1.1 treats no, NO, n, off and similar words as false, so an unquoted country code can silently change type.
  2. 2. How should a version such as 3.10 be written to stay exactly 3.10?

    An unquoted 3.10 is the float 3.1. Quotes keep it a string with the trailing zero.
  3. 3. Why is title: Chapter 1: Intro a problem?

    A colon followed by a space inside a plain scalar is not allowed; quote the whole value.
  4. 4. Which is the safest way to avoid type surprises across YAML parsers?

    Quoting removes the guesswork, and a linter plus schema check catches the rest.

Summary

  • Unquoted YAML values are guessed; YAML 1.1 and 1.2 guess differently.
  • Quote country codes, versions, zip codes, times and anything with : , # or a leading symbol.
  • Avoid tabs and duplicate keys; use true and false only.
  • Lint your YAML and validate the loaded data; use safe loaders.
  • The resolver and linter on this page are teaching models, not production tools.

Next: Configuration Files: Layers, Env Vars and Formats