Common YAML Errors and How to Fix Them

YAML errors are a special kind of frustrating: the file looks correct, the parser disagrees, and the message points at a line two levels away from the real problem. This is a field guide built from the errors people actually paste into issue trackers, ordered by how often they show up.

1. "mapping values are not allowed in this context"

The message:

mapping values are not allowed in this context

Minimal reproduction:

message: Error: not found

Root cause: a colon followed by a space (: ) starts a new mapping wherever it appears. Inside an unquoted value, the second colon is read as a key separator.

Fix: quote the whole value so the colon is just a character:

message: "Error: not found"

2. "could not find expected ':'"

could not find expected ':'

name devtul
age: 30

Root cause: name devtul has no colon, so the parser never sees a key/value pair and chokes when the next line introduces one.

Fix: put the colon and its mandatory space back:

name: devtul
age: 30

3. Wrong nesting from inconsistent indentation

server:
  host: localhost
   port: 8080

Root cause: the second key is indented three spaces while its sibling uses two. YAML treats that as a different level, and if nothing else lives at that level you get a parse error — or worse, a structure you did not intend.

Fix: match the indentation of sibling keys exactly. Use an editor that renders whitespace so the mistake is visible before you save.

4. A tab slipped into the indentation

server:
	host: localhost

(The arrow position is a real TAB character.) Root cause: YAML forbids tabs for indentation. Many editors show a tab as the same width as spaces, so the file looks aligned and still fails.

Fix: expand tabs to spaces. Set your editor to "insert spaces on indent" and re-save the file.

5. "found character that cannot start any token"

found character '@' that cannot start any token

env:
  - @HOME

Root cause: @ (and backtick) are reserved indicators in YAML 1.1. They cannot begin a plain scalar, so the parser rejects the line.

Fix: quote the value, or use a different leading character:

env:
  - "@HOME"

6. Duplicate keys silently overwrite each other

name: alpha
name: beta

Root cause: unlike JSON, YAML does not require implementations to reject duplicate keys. Most parsers keep the last one, so name silently becomes "beta" with no warning.

Fix: never repeat a key at the same level. A linter catches this; a quick parse-and-inspect in the YAML viewer shows which value survived.

7. yes/no/on/off parsed as booleans

enabled: no
debug: off

Root cause: under YAML 1.1 semantics these become the booleans false and false. A feature flag meant to read "no" is now a boolean.

Fix: quote any value that is not a number:

enabled: "no"
debug: "off"

8. Numbers become strings, or strings become numbers

version: 1.10
id: 007

Root cause: 1.10 is parsed as the float 1.1, dropping the trailing zero you probably wanted to keep; 007 is octal 7 under YAML 1.1. Conversely, count: "5" turns a number into a string when downstream code expects an int.

Fix: quote anything whose exact characters matter; leave numbers unquoted only when you truly want a numeric type:

version: "1.10"
id: "007"

9. A multi-line string loses its newlines

text: >
  line one
  line two

Root cause: the folded scalar > converts newlines to spaces, so the value is "line one line two". If you needed the line breaks, this is the wrong indicator.

Fix: use the literal block | to keep every newline:

text: |
  line one
  line two

10. A mistyped anchor name

defaults: &basis
  pool: 5

production:
  <<: *base

Root cause: the alias *base points at an anchor named basis, which does not exist. Depending on the parser you get "unknown alias" or a null merge.

Fix: match the anchor and alias names exactly:

defaults: &base
  pool: 5

production:
  <<: *base

When in doubt, parse it

Half of these errors produce a file that looks fine in an editor and breaks only at runtime. Before you commit, run it through the YAML viewer and read the structure back — the mistakes above almost all show up the moment the parsed tree is in front of you.