YAML Bad Indentation Error, Explained
Unlike JSON, YAML uses whitespace itself to express structure — so indentation isn't cosmetic, it's syntax. A single misplaced space breaks parsing.
What triggers it
- Tabs. The YAML spec forbids tab characters for indentation entirely — only spaces are allowed. An editor that auto-indents with tabs will silently produce invalid YAML.
- Inconsistent indent width. Sibling keys at the same nesting level must line up at exactly the same column. Two spaces for one key and three for the next under the same parent is a parse error, not just a style issue.
- A colon inside a plain (unquoted) scalar value. Since
key: valueis how YAML recognizes a mapping, a value liketime: 10:30confuses the parser — it reads10as the value and30as an unexpected second mapping. Quoting the value (time: "10:30") fixes it. - Mixing block and flow styles incorrectly — e.g. starting a flow mapping (
{ }) or sequence ([ ]) but breaking it across lines without following flow-style continuation rules.
How to fix it
Configure your editor to insert spaces, not tabs, on Enter/Tab (most YAML-aware editors do this by default when they detect a .yml/.yaml extension). Pick one indent width (2 spaces is the near-universal convention) and stick to it throughout the file. When in doubt about a value containing a colon, quote it.
If you just need to convert between formats rather than hand-write YAML, the JSON ⇄ YAML Converter lets you build the structure as JSON — where indentation is not significant — and get valid YAML out.