YAML Indentation Explained: Spaces, Sequences & Mapping Errors

Indentation defines the YAML tree

In block-style YAML, indentation tells the parser which mapping or sequence owns the next node. Two keys aligned at the same indentation are siblings. A line indented farther becomes nested content, while a line that moves back toward the left closes one or more nested blocks.

The number of spaces is a style choice as long as each structural level is unambiguous and siblings remain aligned. Teams often choose two spaces because it is compact and easy to review, but consistency matters more than choosing two versus four.

service:
  name: api
  database:
    host: db.internal
    port: 5432

Use spaces, not tab characters, for indentation

YAML block indentation uses space characters. A tab may be visually similar in an editor but it is not a valid replacement for indentation spaces in block structure. Mixed tabs and spaces can therefore fail even when columns appear aligned on screen.

Configure the editor to insert spaces when pressing Tab in YAML files, and enable whitespace rendering when debugging a configuration copied from another source.

Align sequence items and their nested content

A dash followed by a space introduces a block sequence entry. Sequence item markers at the same level should align. If an item contains a mapping, its following keys need consistent indentation so the parser knows they belong to that item instead of the surrounding mapping.

services:
  - name: api
    port: 8080
  - name: worker
    port: 8081

Indent multiline block scalars as one value

The | and > indicators start block scalar content. The following lines must be indented enough to remain part of that scalar. When a later line de-indents to the surrounding mapping level, the scalar ends and normal YAML structure resumes.

An explicit indentation indicator can be used in advanced cases, but most configuration files are easier to maintain when the scalar's indentation follows naturally from its parent key.

script: |
  echo "start"
  npm test
next: value

Map parser errors back to indentation changes

Messages such as mapping values are not allowed here, could not find expected ':', or expected <block end> are not always caused by the character named in the message. An earlier indentation change may have moved the parser into a different structural context.

Inspect the current line together with the nearest parent key and preceding sibling. Compare their indentation columns before changing punctuation at random.

• Check for tab indentation first.
• Align sibling keys and sibling sequence markers.
• Indent nested mappings farther than their parent key or sequence item.
• Keep multiline scalar content inside its intended indentation block.
• After one correction, parse again so the next reported error reflects the updated structure.