Why does YAML say "mapping values are not allowed here"?

Dark navy cover card with the title 'Why does YAML say "mapping values are not allowed here"?' in white and a green accent bar

YAML says "mapping values are not allowed here" when it reads a colon followed by a space at a point where a new key cannot start. The usual causes are an unquoted value that contains : , or a key indented differently from its neighbours. Quote the value, or line the key up with its siblings, and the error goes away.

What "mapping values are not allowed here" means

The message means the parser found a key-value colon in the middle of something that is already a value. The Ansible YAML syntax guide states the rule: a colon followed by a space (or a newline) is an indicator for a mapping. Every : tells the parser a key just ended.

At the start of a line, that works. On the value side of a line, it doesn't. The PyYAML scanner source raises the error when it meets that colon in block context while a simple key is not allowed.

Go tools use different words. The go-yaml scanner reports it as "mapping values are not allowed in this context". Docker Compose users quote that text, as in this Docker forums thread, and it shows up in GitLab CI pipelines too.

The same broken files in PyYAML and js-yaml

PyYAML and js-yaml catch the same mistakes, but they describe them differently. I ran five broken snippets through PyYAML 6.0.3 (safe_load) and js-yaml 4.1.0 (load). Both stopped at the same line and column every time, and the column pointed at the offending colon.

Input PyYAML 6.0.3 js-yaml 4.1.0
title: Note: read this first mapping values are not allowed here, line 1, column 12 bad indentation of a mapping entry (1:12)
port: 8080 indented one space more than host: mapping values are not allowed here, line 3, column 8 bad indentation of a mapping entry (3:8)
name: web then image: nginx mapping values are not allowed here, line 2, column 8 bad indentation of a mapping entry (2:8)
name: test: unit inside a list item mapping values are not allowed here, line 3, column 15 bad indentation of a mapping entry (3:15)
key:value then other: 1 mapping values are not allowed here, line 2, column 6 end of the stream or a document separator is expected (2:6)

If you work in JavaScript, "bad indentation of a mapping entry" from js-yaml is often the same bug, even when the indentation looks fine, as in the first row.

Cause 1: a colon and space inside an unquoted value

An unquoted value that contains : is the most common trigger. Take this line:

title: Note: read this first

The parser reads title as the key and starts the value Note. Then it hits a second : and tries to start a key mid-value. PyYAML stops at line 1, column 12, which is the second colon.

Quote the whole value. The Ansible guide gives the same fix for its own example, foo: somebody said I should put a colon here: so I did:

title: "Note: read this first"
title: 'Note: read this first'

Both forms loaded cleanly in my test. A trailing colon counts too. The Ansible guide notes that windows_drive: c: fails and should be written as 'c:' or "c:", because a colon at the end of a line is also a mapping indicator.

Cause 2: a key indented one space too far

A key indented deeper than its siblings gets read as part of the previous value. This file looks harmless:

server:
  host: localhost
   port: 8080

YAML lets a plain value continue onto the next line when that line is indented more, so the parser reads the value of host as localhost port, then hits : and fails at line 3, column 8. The same thing happens with name: web followed by an indented image: nginx.

Line the key up with its siblings and the error disappears. If you meant to nest it, the parent needs to end in a colon with no value on that line.

Cause 3: a missing space after a colon

A colon with no space after it is not a key separator, so the whole line becomes a plain value. In key:value, YAML sees one string with a colon in it. The next line, other: 1, then reads as a second key at the top level of a document that is already a single string.

PyYAML blames line 2, column 6, and js-yaml says "end of the stream or a document separator is expected". Neither message mentions line 1, where the real mistake is. When the reported line looks correct, check the line above it.

Colons that do not need quotes

A colon only matters when a space or line break follows it. That is why URLs and ports usually work unquoted:

url: http://example.com:8080/path

This loaded as a plain string in both parsers. The Ansible guide warns about a related trap: a value starting with { is read as a flow mapping, so quote it if you mean text. And a space followed by # starts a comment, which silently cuts off the rest of an unquoted value.

How to find the bad line fast

Read the column number first, because it points at the colon that broke the parse. Then:

  1. Go to the reported line and column. Is that colon inside a value? Quote the value.
  2. Compare the line's indentation with the key above it. Siblings need the same number of spaces.
  3. Look at the line above for a missing space after a colon or a stray extra space at the start.
  4. Run the file through yamllint, which also flags key repetition, trailing spaces and indentation problems.

My take: quote every string value that contains a colon, even when it parses today. It costs two characters, and it keeps the file safe when someone later edits http://host into see: http://host.

The limitation: my table covers only PyYAML and js-yaml. Go tools run go-yaml, which words the error differently, so test with the parser your tool actually uses.

If you are converting YAML to JSON in JavaScript, the YAML to JSON in JavaScript guide covers js-yaml and its errors in more depth. Unquoted no turning into a boolean is covered in the YAML Norway problem, and the file extension question in YAML vs YML. For choosing a config format in the first place, see JSON vs YAML for config files.

FAQ

How do I fix mapping values are not allowed here in YAML?

Look at the colon the error column points to. If it sits inside a value, wrap the whole value in single or double quotes. If it starts a key, fix that line's indentation so it lines up with its sibling keys.

What does mapping values are not allowed in this context mean?

It is the same error from parsers built on go-yaml, which Go tools such as Docker Compose and GitLab CI report. The parser met a colon and space at a point where a new key is not allowed.

Do URLs with colons need quotes in YAML?

Usually not. A URL like http://example.com:8080/path loads fine unquoted, because none of its colons is followed by a space. Quote it anyway if it ends with a colon or contains a space and a hash.

Why does the error point to the wrong line?

The parser reports where it gave up, which is the colon. The real mistake is often a line earlier, such as a missing colon or a key indented one space too far, which made the parser treat the next line as part of a value.

Sources