YAML Indentation Rules (Spaces vs Tabs)
If there's one rule that causes more YAML errors than anything else, it's this: YAML does not allow tab characters for indentation, ever. Only spaces. This trips up more people than any part of the syntax itself.
Why tabs are banned
A tab can be displayed as 2, 4, or 8 spaces wide depending on the editor, which means the same file could look correctly aligned in one program and broken in another. Since YAML relies entirely on indentation to represent structure, that ambiguity was unacceptable to the people who designed the spec — so tabs are simply disallowed in the indentation itself (you can still use a literal tab character inside a quoted string value, just not to indent).
How many spaces should you use?
There's no rule enforced by YAML itself — 2 spaces and 4 spaces are both completely valid. What matters is consistency within one file: every level of nesting needs to step in by the same amount, every time. Two spaces is the more common convention in the YAML world (Kubernetes, most CI configs), largely because deeply nested files stay narrower and easier to read on screen.
The mistake that's invisible until it isn't
server:
host: localhost
port: 8080 # indented one level too many — this is now nested under "host"Because port is indented further than host, YAML doesn't read it as a sibling — it tries to nest it as a child of host, which usually isn't even valid since host already has a plain string value. This is a genuinely easy mistake to make by hand and a genuinely hard one to spot by eye, especially in a long file.
How to actually catch this
- Turn on "show whitespace" in your editor. Most code editors have a setting to render spaces and tabs as visible dots and arrows — turn it on for any file type that includes YAML.
- Set your editor to insert spaces, not tabs, for YAML files specifically, so pressing Tab never inserts the forbidden character in the first place.
- Run it through a formatter before trusting it. Pasting a file into our formatter re-indents it consistently and will immediately flag a structural problem if the indentation actually changes meaning rather than just style.