YAML Indentation Rules: Common Mistakes and Fixes
Master YAML indentation to avoid broken CI/CD pipelines and Kubernetes deployment failures. Learn the strict rules of YAML formatting.
Quick Answer: YAML relies strictly on spaces (never tabs) for indentation to define data hierarchy. If elements are not perfectly aligned vertically, or if a single tab character is present, the YAML parser will throw a fatal syntax error.
YAML (YAML Ain't Markup Language) is loved for its human-readable simplicity, but despised for its unforgiving whitespace rules. A single misplaced space can crash a Kubernetes cluster or fail a GitHub Actions workflow. Understanding exactly how YAML interprets indentation is crucial for any modern DevOps engineer.
Rule 1: Tabs are Strictly Forbidden
The most common YAML error is the TabError. The YAML specification explicitly forbids the use of the Tab character (\t) for indentation. Why? Because different text editors treat tabs differently—some render them as 2 spaces, others as 4, and some as 8. To ensure the file is read identically on every system, YAML forces the use of literal space characters.
The Fix: Configure your IDE (VS Code, IntelliJ) to "Insert Spaces" when you press the Tab key. If you are editing a file in Nano or Vim on a server, manually use the spacebar.
Rule 2: Consistent Spacing (Usually 2 Spaces)
YAML does not enforce a specific number of spaces per indentation level. You can use 2, 4, or 7 spaces if you want. However, you must be completely consistent for children of the same parent node. The industry standard is 2 spaces per level.
# CORRECT: 2 spaces per level
server:
port: 8080
logging:
level: debug
# INCORRECT: Inconsistent spacing
server:
port: 8080
logging: # This has 3 spaces, causing a parser error!
level: debug
Rule 3: Array Lists Need Special Care
Lists (denoted by the hyphen -) often cause confusion. The hyphen itself is considered part of the indentation. The content following the hyphen must be aligned properly if it represents a nested object.
# Correct list of objects
services:
- name: web
image: nginx
- name: db
image: postgres
The Fastest Way to Fix YAML Errors
Staring at a wall of text trying to find a missing space is a waste of time. When your YAML fails to parse, paste it into our YAML Formatter & Validator. The tool will instantly parse the document, pinpoint the exact line and character causing the syntax error, and allow you to auto-format it back into perfectly aligned standard YAML.