YAML Indentation Errors: Reading the Message and Fixing the File

Quick answer

"Mapping values are not allowed here" means the parser hit a colon it can't read as plain text — usually an unquoted value with a colon-and-space inside it, or a line indented to the wrong level. The line number in the error is often a few lines past the real mistake, so check upward first. Three fixes cover most cases: line up sibling keys at the same indentation, put a space after every mapping colon, and quote any value that contains a colon followed by whitespace. (If you've only seen YAML as the block at the top of a Markdown file, that's YAML front matter — same syntax, narrower use case.) The rest of this article covers why YAML behaves this way, the specific patterns that trigger the error, and how to catch the mistake before you save.

Step-by-step

Read the error message first

Before you touch the file, read the error carefully. YAML parsers report the line and column where parsing actually broke — not necessarily where you made the mistake. A missing space or bad indent two lines up can look fine on its own and only cause a visible failure once the parser reaches the next key. Start at the reported line, then walk upward a few lines until the structure stops making sense to you as a human. That's usually where the real fix belongs.

Why indentation alone carries the structure

YAML's block style has no braces or brackets to mark where one section ends and another begins. Indentation is the only signal the parser has. Every nested value has to sit further right than its parent, and every sibling at the same level has to line up at exactly the same column. Get that alignment wrong, and the parser doesn't just format it differently — it builds a different structure than you meant.

Tabs make this worse. The YAML spec explicitly forbids tab characters in indentation, not as a style preference but because different editors and terminals render tab width differently. A file that looks aligned in one editor can be misaligned in another. A single tab hiding in your indentation, invisible in most editors, is enough to trigger a parse error.

Fix the common triggers, in order

Most "mapping values are not allowed here" errors come from one of five patterns:

• An unquoted colon-and-space inside a value, like message: hello: world. The second colon reads as a mapping separator. Quote the whole value: message: "hello: world".
• A missing space after a mapping colon, like key:value. YAML needs that space to recognize the colon as a mapping separator at all — skip it, and you get a confusing error further down the file instead of a clean one on this line.
• A child key indented at the same level as its parent — host: and port: lined up directly under server: with no extra indent, instead of two spaces in.
• A tab character sitting in the indentation where you meant to type spaces.
• A list item's fields not aligned past the hyphen — a run: line under - name: Build that's indented to match the hyphen instead of two spaces past it.

Fix the alignment or the missing space, and the error disappears. If the file still won't parse, re-check the line the error reports. Sometimes one fix exposes a second, unrelated one right below it.

Common problems and fixes

The Norway problem: words that turn into booleans

YAML coerces certain unquoted bare words into booleans instead of treating them as text: yes, no, on, off, true, false, and their capitalized variants. The nickname for this is the "Norway problem" — the country code NO, left unquoted, silently becomes the boolean false instead of the string you meant. It's common enough that GitHub's own workflow syntax explicitly forbids using any of these words as a bare mapping key for exactly this reason. If a value or key is supposed to be one of these words as text, quote it.

Block scalars that lose their indentation

Multi-line values written with a literal (|) or folded (>) block scalar depend on consistent indentation for every line inside them. If one line in the middle loses its indent — often from a paste that didn't carry formatting — it un-nests itself and breaks the block, sometimes without the kind of clean error the mapping-values case gives you. Scan multi-line blocks for a line that sits further left than the rest.

A file that parses isn't a file that's correct

Getting past the parser only confirms the syntax is valid, not that the values are what you meant. Elastic's YAML guidance recommends validating with a linter or the consuming application's own config-check flag before you trust a file, rather than assuming a clean parse means a correct file. The same discipline applies whether you're editing a CI pipeline, an app config, or an SSH config file — a different format with its own structural rules, where a clean read is just as easily mistaken for a correct one.

Doing this with Carets

A lot of these mistakes are invisible until the parser catches them — a tab instead of a space, a line that's one column off from its siblings. Carets gives YAML and other config files syntax highlighting as you type, so indentation levels and whitespace characters are visible on the screen instead of something you have to guess at from memory. It's native and fast on iPhone, iPad, and Mac, so checking or fixing a config file doesn't mean opening a heavier editor just to look at one line. And because Carets organizes files into projects and tags, the config snippets and dotfiles you edit most often stay easy to find instead of scattered across apps.

Download Carets for iPhone, iPad, and Mac.

Frequently Asked Questions

What does "mapping values are not allowed here" mean in YAML?

The parser hit a colon it can't read as part of a plain scalar — almost always an unquoted value containing a colon followed by a space, or a missing space after a mapping colon. Quote the value or add the missing space and the error goes away.

Why does YAML care about indentation so much?

YAML's block style has no braces or brackets to mark nesting — indentation is the only signal for parent-child structure. A child key must sit further right than its parent, and every sibling at the same level must line up exactly, or the parser reads a different structure than you intended.

Can I use tabs to indent a YAML file?

No. The YAML spec explicitly forbids tabs in indentation because different editors render tab width differently, which would make the same file parse differently depending on where you opened it. Use spaces — two per level is the standard.

What is the YAML Norway problem?

It's the nickname for YAML coercing unquoted bare words like yes, no, on, off, true, and false into booleans — so the country code NO can silently become the boolean false. Quote any value that happens to match one of those words if you mean it as text.

How do I check a YAML file is valid before I save it?

Run it through a linter or the consuming application's own config-test flag. A file that parses without error isn't automatically a file that means what you intended — validate the values, not just the syntax.