Why Your YAML Indentation Keeps Breaking (and How to Avoid It)

YAML uses indentation to represent structure the way JSON uses braces and brackets — which makes it readable, but also means a single misplaced space changes meaning instead of just triggering a syntax error you can spot immediately. Here are the specific ways that goes wrong.

Tabs are not allowed, ever

The YAML spec explicitly forbids tab characters for indentation — spaces only. This trips people up constantly because most editors visually render a tab and a few spaces identically, so the file looks fine while the parser rejects it outright. If a YAML file fails to parse with no other obvious cause, check for tabs first — many editors can show whitespace characters explicitly, which makes this instantly visible.

Inconsistent indentation width within one structure

# Wrong — 2 spaces, then 4 spaces, for siblings at the same level
job:
  image: node:20
    env: test

Every key at the same logical level must use the exact same indentation width. Mixing 2 spaces for one sibling and 4 for another doesn't get "close enough" treatment — YAML interprets it as a different nesting level entirely, changing what's actually nested under what.

Lists under a key: two valid styles, don't mix them

# Style 1: list items indented under the key
fruits:
  - apple
  - banana

# Style 2: list items at the same indentation as the key
fruits:
- apple
- banana

Both are valid YAML — the dash itself provides enough structure that the list items don't strictly need extra indentation under their parent key. The failure mode is inconsistency within the same file: picking one style is fine, switching between them from section to section makes a file harder to scan and easier to break during edits.

A nested mapping under a list item

servers:
  - name: web-1
    port: 8080
  - name: web-2
    port: 8081

Here name and port must align to the same column, and that column has to be indented relative to the dash. Get the alignment wrong by even one space and the second key either gets swallowed into the wrong object or rejected as invalid — this specific pattern (a list of objects) is where indentation mistakes happen most often in real Kubernetes manifests and CI configs.

The fastest way to actually find the problem

When a YAML file won't parse and the indentation looks correct to your eye, converting it with our YAML to JSON tool is often faster than staring at whitespace — the error message points at the specific line the parser gave up on, which is usually very close to (though not always exactly at) the actual misalignment. Once you can see the file as JSON's explicit brace-and-bracket structure, it's often obvious which level a value actually landed at versus where you intended it.