YAML Indentation Errors and Silent Surprises in Kubernetes and CI Configs

• ▸Indentation uses spaces only. A tab character is not allowed, and the usual message is that a tab cannot start a token.
• ▸Items at the same level must have exactly the same indentation. One extra space makes a different structure.
• ▸A key needs a space after the colon. name:value is a single string, while name: value is a key and its value.
• ▸A list item needs a space after the hyphen.
• ▸A colon followed by a space inside a value must be quoted, otherwise the parser reads a nested key.
• ▸Comments start with a hash, and need a space before them when they follow a value.

Parser errors give a line and column, but the true problem is often the line before. If a key is indented by the wrong amount, the parser complains at the next line that no longer fits. Mapping values are not allowed here usually means a colon in an unquoted value. Did not find expected key often means inconsistent indentation. Found character that cannot start any token points to a tab or a stray symbol such as an at sign or a percent sign at the start of a value.

YAML guesses the type of unquoted values, and the guess is sometimes wrong in surprising ways.

• ▸The Norway problem: in YAML 1.1 style parsers, unquoted yes, no, on, off, y and n become booleans. A list of country codes containing NO becomes false. Quote them.
• ▸Version numbers: 1.10 becomes the number 1.1, and 3.10 for a Python version becomes 3.1. Quote versions as strings.
• ▸Leading zeros: 0755 can be read as an octal number. Quote file modes and zip codes.
• ▸Dates: 2026-10-03 may become a date object instead of a string, depending on the parser.
• ▸Empty values: a key with nothing after it is null, not an empty string.
• ▸Special tokens: a value beginning with an asterisk, ampersand or exclamation mark is read as an alias, anchor or tag.

The safe habit is to quote any string that is not obviously text, and to let a validator show you what types your parser really produced.

Two block styles are common. A pipe keeps line breaks exactly as written, which suits scripts and certificates. A greater than sign folds line breaks into spaces, which suits long descriptions. Adding a minus after either symbol strips the final newline, and a plus keeps all trailing newlines. Choosing the wrong one changes scripts silently, for example by joining separate commands onto one line.

• ▸Lists of containers, ports and environment variables are lists of mappings. The dash starts the item, and the keys of that item align with the first key after the dash.
• ▸Environment variable values are strings. Quote numbers and booleans such as true and 8080 that must reach the container as text.
• ▸In GitHub Actions, steps are a list, and a run command with a colon needs quotes or a block scalar.
• ▸Keep one document per file where you can. A document separator of three hyphens starts a new document in multi document files.
• ▸Use an editor with visible whitespace and YAML schema validation for Kubernetes and Actions.

Paste the file into the YAML Formatter. It parses first, so a syntax error appears with a line and column, and on success it reprints the document with uniform indentation so structure problems become visible. If the structure looks right but behaves wrong, convert it to JSON with the JSON to YAML Converter and read the types. A value you thought was a string will show as a number, boolean or null, and the surprise is exposed immediately.