Guide

YAML Errors: Fix 'Mapping Values Are Not Allowed Here'

Short answer: the YAML error "mapping values are not allowed here" almost always means a colon sits where YAML does not expect one, usually because of wrong indentation or an unquoted value that contains :. Look at the line the error points to and the line above it, then fix the indentation or quote the value. Paste the file into the YAML Validator to find the exact spot.

What YAML is and why it breaks so easily

YAML is a human-friendly data format used in Kubernetes manifests, Docker Compose files, GitHub Actions workflows, CI pipelines and many app configs. Structure is defined by indentation and a few punctuation marks, not by braces. That makes it pleasant to read and easy to break: one wrong space can change the meaning of the whole file, or make it invalid.

A file can also be valid YAML and still mean something different from what you intended. The validator helps with both.

The errors you will meet most often

1. "mapping values are not allowed here"

Typical causes:

  • Wrong indentation. A key is indented as if it belongs to the previous value.
# Broken
server:
  port: 8080
    host: localhost     # indented too far: looks like part of the port value

# Fixed
server:
  port: 8080
  host: localhost
  • An unquoted value containing a colon and a space.
# Broken
message: Error: something went wrong

# Fixed
message: "Error: something went wrong"
  • Two keys on one line. stage: build script: echo test needs to be on separate lines.

The exact wording differs between parsers (some say "mapping values are not allowed in this context", others report a line number only), but the causes are the same.

2. "could not find expected ':'" or "did not find expected key"

Usually a key without a colon, a list item at the wrong level, or inconsistent indentation within a block. Check the line above the reported line.

3. Tabs used for indentation

YAML does not allow tab characters for indentation. Use spaces. Mixing tabs and spaces is a classic source of confusing errors, and an editor can hide the difference. The validator reports tabs used as indentation.

4. Duplicate keys

Two identical keys in the same mapping are an error in YAML 1.2, and the validator reports them. Some parsers silently keep the last one, which hides the mistake.

user:
  name: John
  age: 30
  name: Jane      # duplicate

5. Unclosed quotes or brackets

A missing closing ", ', ] or } makes the parser read on into following lines. The error often appears far from the real mistake.

6. Unknown aliases

An alias like *base must refer to an anchor &base defined earlier in the document.

The "Norway problem" and YAML 1.1 vs 1.2

In YAML 1.1, unquoted yes, no, on, off, y and n are read as booleans. A list of country codes containing NO for Norway becomes false. This bug has silently broken real configurations.

YAML 1.2 removed that behaviour: only true and false are booleans. But many tools still use YAML 1.1 parsers, so the same file can mean different things in different programs.

The safe approach: quote any value that could be mistaken for a boolean, number or null.

country: "NO"
answer: "yes"
enabled: "on"
version: "1.10"     # without quotes this becomes the number 1.1

The YAML Validator follows YAML 1.2 and warns when an unquoted yes, no, on or off appears, because YAML 1.1 tools would read it as a boolean.

How to fix "mapping values are not allowed here" with the YAML Validator

  1. Open the YAML Validator.
  2. Paste your YAML (or open a file).
  3. Read the result. Syntax problems are reported with their location, and warnings flag ambiguous values.
  4. Fix the first error, then check again. Later errors are often a consequence of the first.
  5. Once the syntax is valid, convert the file with the YAML ⇄ JSON Converter to see how it parses. This is the quickest way to spot a value that turned into the wrong type (more in YAML to JSON: anchors, merge keys and why yes is text).

Checking the shape of the data

Valid YAML is not the same as a correct Kubernetes manifest, Compose file or workflow. The validator checks syntax only. To check that the data has the fields you expect:

  1. Convert the YAML to JSON with the YAML ⇄ JSON Converter.
  2. Validate the JSON with the JSON Schema Validator. If the JSON itself will not parse, see fixing JSON syntax errors.

Limits to know

  • Syntax only, not the meaning of the file for a particular tool.
  • The parser follows YAML 1.2. Programs that use YAML 1.1 may read some values differently, which is exactly what the warnings are for.
  • Custom tags are ignored, and explicit ? complex keys are supported only in simple forms.
  • Invisible characters pasted from a web page or chat can cause strange errors. If a line looks correct but fails, check it with the Hidden Unicode Detector (see How to detect hidden Unicode characters).

Quick checklist before you commit a YAML file

  1. Spaces only, never tabs.
  2. The same indentation width throughout (two spaces is common).
  3. Values containing :, # at the start of a word, or special characters are quoted.
  4. Booleans, numbers and versions that should stay text are quoted.
  5. No duplicate keys.
  6. Every opening quote and bracket is closed.
  7. Run it through a validator.

Frequently asked questions

How do I validate a YAML file? Paste it into the YAML Validator and read the reported errors and warnings.

Why does YAML not allow tabs? The specification forbids tabs for indentation to avoid ambiguity about how wide a tab is.

What does ~ or an empty value mean? Both mean null in YAML. name: with nothing after it is null, not an empty string. Use "" for an empty string.

Is YAML a superset of JSON? YAML 1.2 was designed to be, so most JSON is valid YAML. Edge cases still exist.

YAML or TOML? TOML avoids indentation problems and suits simple configuration. See the TOML validation guide.

Related tools and guides

Sources and further reading