Skip to main content
DevOps Insightsguides & answers

YAML · troubleshooting

yaml: mapping values are not allowed in this context

The parser met a colon followed by a space where a new key cannot start. Usually a value that itself contains ": " and is not quoted, two keys on one line, or a line indented further than the keys beside it.

Reproduced on Helm 3.18.2, . Where the text says “reproduced”, the behaviour was run on that version, not taken from documentation.

First published

New to this? Read what is actually happening first, then come back to the steps.

On this page · 8 sections

Before you start

  • The file and the line number from the message (Helm values, a Kubernetes manifest, a Compose or CI file).

Run this first

step 1 of 1
python3 -c 'import sys,yaml; yaml.safe_load(open(sys.argv[1]))' FILE

Look for in "FILE", line N, column M

A second parser (PyYAML, if installed) names the line and column it stopped at, which can be clearer than the Go library's line number.

Work out which cause you have

A few questions to narrow the list. Every answer ends in a command that confirms or rules the cause out — this cannot see your cluster, so nothing here is a certainty until you have checked.

Narrow it down

0 answered · nothing is sent anywhere

What is on the line the error names, or the one before it?

Cause space

3 of 3 still possible

  • A value contains ": " and is not quotedCommon
  • Two keys on one lineCommon
  • A line indented further than its siblingsCommon

Nothing ruled out yet. Answer the question above and the branches your answer eliminates will strike through here.

Or diagnose it manually

In this order. The first command usually contains the whole answer.

  1. Step 1

    python3 -c 'import sys,yaml; yaml.safe_load(open(sys.argv[1]))' FILE

    A second parser (PyYAML, if installed) names the line and column it stopped at, which can be clearer than the Go library's line number.

    Look for in "FILE", line N, column M

Every cause, and how to fix it

Ordered by how often each one turns out to be the answer.

A value contains ": " and is not quoted

Common

Messages, URLs with ports in odd places, commands such as echo time: now, or Windows paths: the colon-space inside the value looks like a new key.

Confirm

sed -n 'Np' FILE

A value with ": " inside it on or just before line N

Fix

  • Quote the whole value: message: "Error: something failed". Use single quotes if the value contains double quotes or backslashes.
message: "Error: something failed"

Reproduced on Helm 3.18.2: the unquoted form fails, the quoted one renders.

Two keys on one line

Common

image: repository: nginx tries to start a mapping inside a value. The nested key belongs on its own line, indented.

Confirm

grep -nE '^ *[A-Za-z0-9_.-]+: +[A-Za-z0-9_.-]+: ' FILE

A line with two key: parts

Fix

  • Put the nested key on the next line, indented by two spaces under its parent.

A line indented further than its siblings

Common

Inside a list item, the keys after the first must line up with the first key, not with the dash. One extra level makes the parser read the line as a value of the line above.

Confirm

cat -et FILE | sed -n 'N,+3p'

Keys at different indents inside one block (cat -A on Linux)

Fix

  • Line the keys up: in - name: http, the next key starts under the n of name.

Understanding it properly

Skip this if you are mid-incident — the working part of the page is above. Worth reading afterwards, because understanding the mechanism is what stops the next one.

In plain terms

In YAML, a colon followed by a space means "key: value". When that pattern appears inside a value, or on a line that is indented as if it belonged to the line above, the parser cannot tell what is a key, and stops. The fix is almost always quotes or indentation.

Words used on this page

Mapping
YAML's key: value structure. A colon followed by a space starts one.
Plain scalar
A value written without quotes. It cannot contain ": " or start with certain characters.
What is actually happening

Reproduced with Helm 3.18.2 rendering a chart whose values.yaml was edited. message: Error: something failed, an unquoted value containing ": ", failed with Error: cannot load values.yaml: error converting YAML to JSON: yaml: line 3: mapping values are not allowed in this context. Quoting the value fixed it.

Two keys on one line, image: repository: nginx, gave the same error with no line number at all. A key indented further than the first key of its list item, port: under - name: http, gave it too, at line 3.

The text after yaml: comes from the Go YAML library that Helm, kubectl and other Kubernetes tools share, so the same file gives the same message in each, after the tool's own prefix. Only Helm's output was captured here.

Python tools, Ansible among them, parse YAML with PyYAML, which words it differently: PyYAML 6.0.3 printed mapping values are not allowed here, with the line and column (line 1, column 11 for the unquoted colon).

How to tell this is your problem
WhereWhat you see
helm template, install, upgradeError: cannot load values.yaml: error converting YAML to JSON: yaml: line N: mapping values are not allowed in this context
Other Kubernetes tools... error converting YAML to JSON: yaml: line N: mapping values are not allowed in this context

How to know it is actually fixed

  • helm template (or kubectl apply --dry-run=client) parses the file without a yaml: error.

Stopping it happening again

  • Quote any value that contains a colon, starts with a special character, or could look like a number or boolean.
  • Let your editor show whitespace in YAML files, and run helm lint or a YAML linter in CI.

Sources

Behaviour described here is drawn from official documentation. Where a figure could not be confirmed on an official page it is attributed in the text rather than stated as canonical.

Did this get you to an answer?

No text box on purpose — please do not paste production logs anywhere

Something wrong or out of date? Report it

Where to go next