Can YAML indentation use tabs?

No. YAML indentation must use spaces.

How many spaces should YAML use?

The specification does not mandate one width, but sibling nodes must align consistently; two spaces is common.

Why can valid-looking YAML parse differently?

Indentation changes nesting, and unquoted scalars can be interpreted according to YAML syntax and parser version.

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: value is how YAML recognizes a mapping, a value like time: 10:30 confuses the parser — it reads 10 as the value and 30 as 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.

Confirm the parsed structure

A file can become syntactically valid after re-indenting and still describe the wrong object. Compare the parsed JSON form before and after the edit, especially for lists of mappings and nested configuration blocks. A single misplaced dash can turn one object into several items, while a key moved two spaces can attach to the wrong parent.

For CI, parse every YAML file with the same library and YAML version used by production, then validate the resulting object against a schema when one exists. Quote ambiguous scalar values such as dates, booleans, and values containing : when they must remain strings. This catches semantic changes that a basic syntax check cannot see.

Frequently Asked Questions

Can indentation use tabs?

No. YAML indentation uses spaces.

How many spaces should I use?

Two is common, but consistent sibling alignment matters more than a specific width.

Why can repaired YAML still be wrong?

Indentation controls nesting, so a syntactic repair can change which parent owns a value.