Why does YAML require indentation?

YAML uses whitespace indentation to represent hierarchy and nested structure instead of explicit brackets or braces. An object nested inside another object must be indented further right. This makes YAML very human-readable but also means a single misplaced space changes the data structure or causes a parse error.

What causes "mapping values are not allowed here" in YAML?

This error usually means a colon appeared where the parser did not expect one. Common causes: (1) A colon in a string value that is not quoted — write key: "value:with:colons" not key: value:with:colons. (2) A key-value pair is indented at the wrong level, orphaning it from its parent mapping. (3) A tab character before a key (YAML tabs cause the parser to misread indentation).

Can I mix 2-space and 4-space indentation in YAML?

Yes, but only within the same level of nesting. Each level must be consistently indented relative to its parent. For example, if a parent key is at column 0, all its children must be at the same column (e.g., all at 2). You cannot have some children at 2 spaces and others at 4 spaces within the same parent — that is an indentation error. Best practice: pick one size (2 spaces recommended) and stick to it throughout the entire file.

How do I fix tabs in YAML?

YAML prohibits tab characters for indentation. In most editors: VS Code — open Settings, search "insertSpaces" and enable it, then use Editor: Tab Size 2. Vim — add ":set expandtab" and ":set tabstop=2" to your .vimrc. To convert existing tabs to spaces in a file, most editors have a "Convert Indentation to Spaces" command. You can also use sed: sed -i "s/\t/ /g" file.yaml

YAML & Configuration

YAML Indentation Errors: How to Find and Fix Them

YAML uses whitespace to define structure. A single extra space — or a tab where a space belongs — can silently corrupt your data or cause a cryptic parse error. Here's how to read the error messages and fix each type.

Most Common Indentation Errors

• found character '\t' that cannot start any token — tab character used instead of spaces
• mapping values are not allowed here — colon at wrong indent level or in unquoted string
• did not find expected key — indentation inconsistency at the same level
• unexpected end of mapping — child elements over-indented beyond parent

Error 1: Tabs Instead of Spaces

YAML strictly prohibits tab characters (\t) for indentation. This is the most common error for developers whose editor defaults to inserting tabs.

Invalid (tabs)

server:

→ host: localhost ← tab

→ port: 8080 ← tab

Error: found character '\t' that cannot start any token

Valid (2 spaces)

server:

host: localhost ← 2 spaces

port: 8080 ← 2 spaces

Fix in your editor

VS Code: Settings → "Editor: Insert Spaces" → enable; "Tab Size" → 2

Vim: :set expandtab | :set tabstop=2 | :set shiftwidth=2

Command: sed -i 's/\t/ /g' file.yaml (replace tabs with 2 spaces)

Error 2: Inconsistent Indentation at the Same Level

All keys in the same mapping must align at exactly the same column. Mixing 2-space and 3-space children causes a parse error.

Invalid (mixed depth)

database:

host: localhost ← 2

port: 5432 ← 3 !

name: mydb ← 2

Error: did not find expected key

Valid (consistent 2-space)

database:

host: localhost

port: 5432

name: mydb

Error 3: "Mapping Values Are Not Allowed Here"

This error appears when a colon appears where the parser doesn't expect one. There are two common causes:

Cause A: Colon in an unquoted string value

Invalid

url: http://localhost:3000

message: Error: file not found

Valid (quoted)

url: "http://localhost:3000"

message: "Error: file not found"

Cause B: Wrong indentation of a nested key

Invalid (orphaned key)

settings:

timeout: 30

retries: 3 ← should be indented

Valid

settings:

timeout: 30

retries: 3

Error 4: List Item Indentation

List items use - followed by a space. The dash must be indented at least one space more than the parent key. Keys inside a list item must be indented further than the dash.

Invalid

servers:

- name: web1

ip: 10.0.0.1 ← not aligned

- name: web2 ← extra space

Valid

servers:

- name: web1

ip: 10.0.0.1

- name: web2

ip: 10.0.0.2

Error 5: Indentation After Multi-line Strings

Block scalars (| literal or > folded) must be indented more than their key. Keys after the block scalar must return to the correct level.

Invalid

config:

script: |

echo hello

echo world

timeout: 30 ← OK, but if it was indented 4+, error

Valid

config:

script: |

echo hello

echo world

timeout: 30 ← same level as script

Debugging YAML Indentation

Enable whitespace visualization

In VS Code: View → Render Whitespace → All. This shows · for spaces and → for tabs, making invisible characters visible.

Use a YAML validator

Paste your YAML into our YAML Validator tool to get a precise error location (line and column number). Browser parsers give much clearer error messages than most CI systems.

Use yamllint

Install yamllint (pip install yamllint) and run: yamllint -d relaxed file.yaml. It shows every indentation problem with line numbers and rule names.

Set up EditorConfig

Add a .editorconfig file to your project root: [*.yaml] indent_style = space / indent_size = 2. Most editors respect this and will auto-convert tabs to spaces.

Check for zero-width characters

If your YAML comes from a web form or chat app, it may contain zero-width spaces (U+200B) or other invisible characters that look like spaces but aren't. Use a hex editor or online tool to detect them.

Frequently Asked Questions

Why does YAML use indentation instead of braces?

YAML was designed for human readability and editing. Indentation-based structure reads more like natural text and eliminates visual clutter (no brackets, no commas). The trade-off is that whitespace becomes significant, which can be surprising for developers used to languages that ignore whitespace. JSON (which uses braces) was designed for machine-to-machine data exchange and is more lenient about whitespace.

Does it matter if I use 2-space or 4-space indentation in YAML?

No — YAML does not mandate a specific number of spaces. Each level just needs to be indented more than its parent, and all siblings at the same level must match. 2 spaces is the community convention (Kubernetes, GitHub Actions, Ansible all use it) and is recommended for readability. The only rule: tabs are never allowed.

How do I fix YAML indentation in VS Code?

Right-click in the editor and choose "Format Document" if a YAML formatter extension is installed (Prettier or YAML by Red Hat). Alternatively, open the Command Palette (Ctrl+Shift+P), search "Convert Indentation to Spaces", and set tab size to 2. The YAML extension by Red Hat also shows indentation guides and highlights errors inline.

Why does "kubectl apply" fail with an indentation error even though my YAML looks correct?

Common causes: (1) Copy-pasted from a website that converted spaces to HTML non-breaking spaces ( ). These look identical to regular spaces but are not valid YAML. (2) Your terminal editor inserted actual tabs. (3) The file has Windows line endings (CRLF) which confuse some YAML parsers on Linux. Run: cat -A file.yaml | head -20 to see hidden characters (tabs show as ^I, Windows endings as ^M$).

Key Takeaways

Tabs are never allowed in YAML — configure your editor to insert spaces.
All siblings at the same level must be at exactly the same column.
"Mapping values not allowed here" usually means a colon in an unquoted string — wrap it in quotes.
Enable whitespace visualization in your editor to see spaces vs tabs at a glance.
Use yamllint or our YAML Validator for exact error location and rule explanation.

Related Resources

YAML Validator

Validate your YAML and see exact error location

JSON vs YAML

When to use YAML vs JSON

Docker Compose Env Variables

Set env vars correctly in YAML

Docker Compose Port Errors

Fix docker compose port conflicts