How to Format YAML (Indentation, Rules, and Common Errors)

YAML runs a huge share of modern infrastructure: Kubernetes manifests, Docker Compose files, GitHub Actions workflows, and countless application configs. It is readable precisely because it uses indentation instead of brackets to express structure. That same feature is why a single misplaced space can break an entire file. This guide covers the indentation rules that actually matter, the errors that show up most often, and the fastest ways to format YAML so it stays valid.

The fastest route: an online formatter

For a quick cleanup, paste your YAML into the YAML formatter. It parses the YAML, validates it, and rewrites the whole file with even two or four space indentation. Because it parses then re-serializes rather than nudging lines around, the output is guaranteed well-formed. If the YAML cannot be parsed, you get the error instead of a silently broken file, and it all runs in your browser so a config full of secrets never leaves your machine.

That matters because the most common YAML problems are not logic errors, they are whitespace errors, and re-emitting the file from a parsed structure fixes every one of them at once.

Why indentation is everything in YAML

Unlike JSON, which marks structure with {} and [], YAML marks it with indentation. Keys that are indented further are nested inside the key above them, and keys at the same indent are siblings. Get the indent wrong and you do not get a slightly off file, you get a different structure or a parse error.

server:
  host: localhost
  ports:
    - 80
    - 443

Here host and ports are children of server because they are indented one level in, and the two port numbers are list items under ports. Shift any of those lines and the meaning changes.

The core rules

Most YAML errors come down to a short list of rules. Learn these and the majority of problems disappear.

• Spaces only, never tabs. This is the single biggest source of YAML errors. YAML forbids tabs for indentation. An editor that inserts a tab produces a file that looks fine but will not parse.
• Be consistent. Pick two spaces per level (the common convention) or four, and use the same width everywhere. Mixing widths confuses both humans and parsers.
• Nest by indenting further. A child is always indented more than its parent. Siblings share the exact same indentation.
• Put a space after the colon. A mapping is written key: value with a space after the colon. key:value is not the same thing.
• Mark list items with a dash. Each item in a sequence starts with -, indented under its key.

The errors that bite most often

A handful of messages account for most of the YAML errors developers hit.

bad indentation of a mapping entry means a line is indented in a way the parser cannot reconcile with the lines around it. Usually a tab crept in, or a nested block is under-indented by a space. The fix is to normalize the whole file to consistent spacing.

could not find expected ':' usually means a mapping line is missing its colon, or a value contains a special character and needs quoting. Strings with a leading @, a : inside them, or a value like yes or no that YAML would read as a boolean often need quotes.

mapping values are not allowed here typically means a colon appears where YAML did not expect one, often because a value with a colon in it (like a URL or a time) was left unquoted. Wrap the value in quotes: time: "12:30".

In every one of these cases, running the file through a formatter that parses and re-emits it either fixes the problem or points to the exact line, which is faster than hunting for an invisible space by eye.

Tabs versus spaces, and how to stop the problem at the source

Because tabs are the top cause of YAML breakage, it is worth fixing in your editor rather than cleaning up after the fact. Configure your editor to insert spaces when you press Tab, and to show whitespace characters so a stray tab is visible. In VS Code, set "editor.insertSpaces": true and "editor.detectIndentation": false for YAML files. Many teams also add a linter like yamllint to catch tabs and inconsistent indentation in CI before a bad file ever merges.

Formatting YAML from the command line

If you prefer the terminal, a few tools format YAML well. yq can read and re-emit YAML with normalized formatting:

yq -P '.' config.yaml

The -P flag pretty-prints with clean indentation. prettier also handles YAML and is convenient if it is already in your toolchain:

npx prettier --write config.yaml

Both parse the file fully, so like the online formatter they will reject invalid YAML rather than produce a broken result. For a one-off, the browser tool is faster; for a repo you format repeatedly, wiring prettier or yq into a pre-commit hook keeps every file consistent automatically.

YAML and JSON are closer than they look

A useful fact: every valid JSON document is also valid YAML. YAML is a superset of JSON, so you can paste JSON straight into a YAML parser and it will accept it. That is why the same formatter can often help whichever format you are working in, and why teams frequently move config between the two. If you work with both, the JSON formatter beautifies JSON the same way, the JSON parser pinpoints JSON syntax errors, and the JSON viewer renders large JSON as a collapsible tree, and the JSON minifier strips it back down for production. If you are newer to the format underneath all this, the guide on what JSON is covers its data types and structure.

When you need to move between formats rather than just tidy one, the JSON to XML converter handles that direction, and the XML formatter cleans up the result.

Frequently asked questions

Can I use tabs to indent YAML?
No. YAML does not allow tabs for indentation, only spaces. A tab is the most common reason a YAML file fails to parse. Configure your editor to insert spaces, and run the file through the YAML formatter to convert any tabs that slipped in.

How many spaces should I use for YAML indentation?
Two spaces per level is the most common convention and what most tools default to. Four is also fine. The rule that matters is consistency: use the same width throughout the file.

Does formatting YAML change my data?
No. Formatting only changes whitespace, and key order if you turn on sort keys. The values and structure stay exactly the same.

Why does my YAML value get read as a boolean?
YAML interprets bare words like yes, no, on, off, and true as booleans. If you want the literal string, quote it: enabled: "no". The same applies to values that look like numbers or dates.

For the rest of the toolkit, including validating, minifying, and converting JSON, see the roundup of free JSON tools.