YAML Error Mapping Values Are Not Allowed Here Fixed

This is the most common error message PyYAML produces, and it is not helpful. It does not say which of several different mistakes you made. They all look the same to the parser: a colon followed by a space appeared at a point where it cannot start a new key, so the parser gives up. Here are the three causes I find in real files, what each looks like in the error, and the one-line fix.

What the message means

In a block mapping, a key and its value are separated by a colon and a space. The scanner reads a plain scalar, an unquoted value, until it sees something that ends it. A colon followed by a space ends a scalar and says "what came before was a key". If a key cannot start at that point, the parser reports that mapping values are not allowed. The text varies by parser:

PyYAML (Python loader) : mapping values are not allowed here
libyaml / CSafeLoader  : mapping values are not allowed in this context
yq (Go)                : go-yaml load error in scanner at L2.C9: mapping values are not allowed in this context

The line and column agree across all three, and that position is the useful part: it points at the second colon, the one that should not be there, or at the colon on the line that is out of place.

Cause 1: a colon inside an unquoted value

The most frequent case is plain text that contains : , such as an error message, a time, a URL with a port written with spaces or a sentence:

msg: Error: disk full

mapping values are not allowed here | line 1, column 11

Column 11 is the colon after Error. The scanner read msg as a key, then Error as the start of the value, then saw a colon and a space and concluded that Error is itself a key. A mapping value cannot start on the same line as its parent key, so it stops. The fix is to quote the value:

msg: "Error: disk full"

Use double quotes when the text contains a single quote, single quotes otherwise. If the text is long, use a block scalar (msg: | and the text on the next lines), where colons are ordinary characters (YAML multiline strings with pipe and greater than).

The same failure appears when someone writes two values for one key:

name: web
port: 80: 90

mapping values are not allowed here | line 2, column 9

The author may have meant a range or a port mapping. Quote it (port: "80:90") if it is one string, or restructure into two keys (port_from, port_to) if it is two numbers. Note the colon-without-space form 80:90 is not an error at all: it needs the space after the colon to count as a mapping separator. It is, however, a base-60 number in YAML 1.1 if the parts are valid digits, a separate trap (why a number turns into something else in YAML).

Cause 2: a line indented one space too far

The second cause has nothing to do with colons in values. It is alignment:

server:
  host: db1
  port: 5432
   timeout: 30

mapping values are not allowed here | line 4, column 11

timeout has three spaces of indentation where host and port have two. The scanner treats a more-indented line after a plain scalar as a continuation of that scalar, so it reads 5432 timeout as the value of port, and then hits the colon after timeout. Column 11 is that colon. The fix is to align the key with its siblings:

server:
  host: db1
  port: 5432
  timeout: 30

The error line is the line after the real mistake in structure terms. The mistake is the extra space on line 4, and the colon at the end of the line is where the parser notices. When the highlighted line looks right, count the spaces of the lines above. A linter that reports indentation, such as yamllint, names the line more precisely in this case (fixing YAML indentation errors with a linter).

Cause 3: a mapping where a scalar is required

A third form arises when a key is put where YAML expects a value on the same line, for example after a sequence indicator or inside flow style:

- name: web: prod

ports: [80, 443: 8443]

The first reads web as a value and then sees another colon, so the same quoting rule applies: - name: "web: prod". The second is a flow sequence containing a pair, which flow style allows only as a single-pair mapping in specific forms and which most people did not intend. If you meant a mapping, use braces: ports: {443: 8443}. If you meant strings, quote them.

A fast way to find which cause it is

1. Look at the column. If it points at a colon in the middle of text, you have cause 1. Quote that value.

2. If it points at a colon on a line whose key is in the wrong column, compare the indentation with the lines above. Cause 2.

3. If the line has several colons or brackets, you have cause 3 or a value that needs to be quoted.

4. Still unsure: run yamllint on the file. It reports the exact rule (syntax error: mapping values are not allowed here along with indentation findings for the lines above).

After the fix, load the file and print the result. The error is gone when the parse succeeds, and the printed structure shows whether the values are what you meant: a value that was quoted is a string, one that was realigned is where you wanted it.

Related reading

The cluster hub is fixing YAML errors that make no sense. Related errors: found character that cannot start any token, did not find expected key and could not find expected colon. The scanner rules are in section 7 of the YAML 1.2.2 specification, and PyYAML's behavior in its documentation. Check a fixed file in the YAML to JSON tool.

When the error points at the wrong line

The mistake is above. An unclosed quote or bracket earlier in the file swallows the lines after it, and the error appears where the swallowing ends. Look for a quote that opens and never closes.

A tab or a non-breaking space. A tab fails with its own message. A non-breaking space, however, does not fail at all: a test with two non-breaking spaces as indentation loaded as a key named with those characters (finding tab characters hiding in a YAML file).

A template produced the file. If a templating step generated the YAML, the bug is in the template. Print the rendered text and read that.

The file is a different format. A file that is JSON with a trailing comma, an INI file or a Markdown file with front matter can trigger the same message. Check the file type first.