YAML Lint / Errors

"mapping values are not allowed here"

The parser found a : where it could only parse a scalar. Almost always this means an unquoted value contains a colon-then-space, or two key-value pairs share a line. Quote the value, split the line, or fix the indentation.

Paste your YAML to find the line →

The error in context

You'll see one of these:

yaml.scanner.ScannerError: mapping values are not allowed here
  in "<unicode string>", line 4, column 12

YAMLException: bad indentation of a mapping entry at line 4, column 12

Error: mapping values are not allowed in this context

Every form points at the same conflict: a : appeared in a position where the parser had committed to reading a scalar, not starting a new key.

The three patterns

1. Unquoted colon-then-space in a value

title: Released: now available
            ↑ this colon-space is a new mapping

Fix: quote the value.

title: "Released: now available"
title: 'Released: now available'

Same fix for time-of-day, version strings, dictionary entries, and anything else where a literal colon is meaningful:

start: "09:00"
note: "see: README.md"
header: "Authorization: Bearer ..."

2. Two mappings on one line

name: alice age: 30
            ↑ "age" looks like a second key

Fix: split into two lines, or use flow style:

# Block style
name: alice
age: 30

# Flow style
{ name: alice, age: 30 }

3. Wrong indentation aligning a value with a key

config:
key: value      ← should be indented
            ↑ "key" is read as a new top-level mapping inside "config"

Fix: indent consistently. YAML doesn't care about the exact number of spaces (as long as siblings match), but tabs are forbidden in indentation:

config:
  key: value

Cases that look right but aren't

Comments without leading whitespace

port: 8080#dev   ← '#' is part of the value, then ':' on next line breaks

Fix: port: 8080 # dev.

URLs that include a path with a colon

repo: https://example.com/path:tag

OK as-is — the second colon has no following space. But this:

repo: https://example.com/path :tag

Breaks. The space before :tag ends the scalar.

Multi-line values that want a colon

Use a literal block scalar (|) or folded (>):

note: |
  Released: now available.
  Multiple lines preserved.

See YAML multi-line strings for the differences between |, >, and the chomping indicators.

Why YAML is like this

YAML's design goal is "readable for humans first." That mostly works, except where context-free intuition collides with the format's mapping syntax. The colon doubles as both a key/value separator and (sometimes) a literal character — but only based on what's around it. Quoting is the unambiguous escape hatch.

See also the YAML vs JSON trade-offs and the anchors / aliases guide for the more advanced syntax.

FAQ

Why does YAML care about a colon in a value?

Because ':' is YAML's mapping indicator. Inside a flow scalar, a colon followed by a space (or the end of line) starts a new mapping. The parser sees what looks like a second mapping and refuses because it's already inside one.

Do I need to quote every value with a colon?

Only when the colon is followed by a space, when the value starts with a colon, or when other YAML metacharacters are present (#, &, *, !, |, >, etc.). 'http://example.com' is fine because there's no space after the colons. 'See: this' is not.

Why did this break after I added a comment?

Comments must be preceded by whitespace. 'key: value#comment' is not a comment — it's the value 'value#comment'. If a colon comes later in 'value#comment: more', the parser fires this error.

Single quotes or double quotes — does it matter?

For this error, no — both prevent the colon from being interpreted as a mapping. They differ on escapes: double quotes process \n, \t, \". Single quotes are literal except '' (which escapes a single quote). Use single by default; switch to double when you need escapes.

Is this the same as 'did not find expected key'?

No, but they're cousins. 'mapping values are not allowed here' fires when an unexpected colon appears in a value. 'did not find expected key' fires when the parser was waiting for a key and got something else — usually wrong indentation. Both stem from YAML's strict structure but the fixes differ.

Open the linter →