YAML Gotchas: The Norway Problem, Tabs, and Multiline Strings

YAML is everywhere — Kubernetes manifests, CI pipelines, application config — because it reads like plain text. That readability hides a surprising number of foot-guns, and they tend to surface at the worst time: a deploy that silently does the wrong thing because a value was parsed as a boolean, or a pipeline that refuses to start over an invisible tab. Here are the ones that bite most often.

The Norway problem

The single most infamous YAML gotcha: unquoted NO (the country code for Norway) parses as the boolean false. The same applies to yes, no, on, off, true, false, and their capitalized variants under older YAML 1.1 parsers. So this:

countries:
  - NO
  - SE
  - FR

can become [false, "SE", "FR"]. A config key like enabled: no becomes enabled: false, which is usually what you meant — until the value is a string that just happens to look boolean. The fix is quoting: "NO", "yes". When in doubt about how a value will be interpreted, paste it into the YAML Validator and look at the JSON it produces — that shows you the actual parsed types, not what you assumed.

Tabs are illegal

YAML uses spaces for indentation, and tabs are not allowed as indentation. Worse, a tab is invisible in most editors, so a file that looks perfectly aligned throws a cryptic parse error. If a YAML file refuses to load and the indentation "looks fine," suspect a tab. Configure your editor to show whitespace and to insert spaces, and validate structure with the YAML Validator before shipping.

Numbers that aren't numbers (and versions that aren't strings)

A few more type surprises:

• Leading zeros and colons. version: 1.10 is a float and becomes 1.1. A time like 12:00 can parse as a sexagesimal number. Quote version strings: version: "1.10".
• Octal and hex. 080 may error (invalid octal) or parse unexpectedly depending on the parser.
• Null-ish values. ~, null, Null, and an empty value all mean null. An empty key: is null, not an empty string.

The theme is consistent: if you mean a string, quote it. Quoting costs nothing and removes almost all of these ambiguities.

Multiline strings: | vs >

When you need a block of text (a script, a certificate, a long message), YAML gives two block styles that people constantly mix up:

• Literal | keeps newlines exactly as written. Use it for shell scripts, PEM keys, anything where line breaks matter.
• Folded > replaces single newlines with spaces (folding the block into one line), keeping blank lines as paragraph breaks. Use it for prose that should wrap.

Add a chomping indicator to control the trailing newline: |- strips it, |+ keeps all of them, plain | keeps a single one. Getting this wrong is why an embedded key or script sometimes has a stray blank line or is missing its final newline.

A pre-flight habit

Because YAML fails in quiet, type-level ways, the cheap insurance is to validate and inspect the parsed output before it reaches production. Convert the file with the YAML Validator and skim the resulting JSON — mismatched types (a string that became a boolean, a version that became a float) jump out immediately. If you are hand-editing large blocks, the JSON Formatter is handy for reading the converted result, and the Diff Checker helps compare two config versions when a deploy behaves differently than the last one.

The short version

YAML's readability is real, but so are its traps: quote anything that looks boolean or numeric, never indent with tabs, and know your | from your >. Validate the parsed types before you ship, and the "why did my config do that?" mysteries mostly disappear.