YAML Error Could Not Find Expected Colon and Its Causes

You edit a long file, add a line of notes, save, and the parser says it could not find an expected colon. This error has a simple meaning and a misleading position: it points at the line after the problem. Once you know that, it takes seconds to fix. This post shows the message from three parsers, the four mistakes that cause it and the fix for each.

What the parser is doing

In a block mapping, each line is a key, a colon and a value. When the scanner starts a line and sees text that is not a dash, a quote, a bracket or another indicator, it assumes it is the start of a simple key and reads until it finds a colon. The key may not span lines. If it reaches the end of the line without a colon, it stops with this error.

The smallest reproduction:

a: 1
b
c: 2

PyYAML (pure Python) : while scanning a simple key | could not find expected ':' | line 3, column 1
CSafeLoader (libyaml): while scanning a simple key | in "e4.yaml", line 2, column 1 | could not find expected ':' | in "e4.yaml", line 3, column 1
yq (Go)              : go-yaml load error in scanner (while scanning a simple key) at L2.C1-L3.C1: could not find expected ':'

The offending text, b, is on line 2. The error is reported at line 3, column 1, the start of the next line, because that is where the scanner gave up looking. The libyaml and yq messages show the span from line 2 to line 3 (context from the start of the key to the point of failure), which tells you where the key began. In the Python loader's plain message only the failure position appears. Always look at the line above the reported one.

Cause 1: a value or a colon was deleted

The most common cause is an incomplete edit. A key without a value is fine (b: is a key with null), but a key without its colon is not:

server:
  host: db1
  port
  tls: true

while scanning a simple key | could not find expected ':' | line 4, column 3

The line port lost its colon and value. The scanner reads port, reaches the end of the line and keeps looking, then gives up at the start of line 4. The fix is port: 5432, or port: if the value should be null. Note the position: line 4, the line after the stray word. In long files this happens after search-and-replace operations or when a colon was typed over. One variation behaves differently: when the bare word is followed by a more-indented line, as in database then host: db1, the parser reads the second line as a continuation of the first and reports "mapping values are not allowed here" instead, so the same mistake can produce either message.

Cause 2: a line wrapped without indentation

A long value that was wrapped by an editor or pasted from an email may continue on the next line at the same indentation as the key:

description: This text is long enough that someone
broke it into two lines
owner: platform

The second line starts at column 1, so the parser sees broke it into two lines as a new key and looks for its colon. Two fixes. If the text is one string, indent the continuation more than the key, and the parser folds it into the previous value with a space:

description: This text is long enough that someone
  broke it into two lines

That loads as one string, This text is long enough that someone broke it into two lines. For text with colons or special characters, or text longer than a line or two, use a block scalar (description: > and the lines indented below), which is made for it (YAML multiline strings with pipe and greater than).

Cause 3: a comment marker is missing

Free text pasted into a file with the intention of commenting it, but without the hash, is read as a key:

timeout: 30
this is the timeout in seconds
retries: 3

The second line is an explanation that lost its #. The scanner reads this is the timeout in seconds as a key and finds no colon. The fix is to add the hash: # this is the timeout in seconds, or timeout: 30 # seconds. If your editor has a "comment selection" shortcut, use it, so the hash is added to every line of a block.

Cause 4: a dash is missing in a list

In a list of scalars, every item needs a dash:

features:
  - search
  export
  - billing

The line with export has no dash, so it looks like a key without a colon. In a list of mappings the same error appears when a new item starts without its dash and the first key is followed by no colon, or when the dash is there but the keys are misaligned. Add the dash and the space after it.

How to find it fast

1. Take the reported line and go up one. The stray text is usually there. If the line above is blank or a comment, go up to the nearest content line.

2. Look for a bare word or sentence with no colon, at the start of a line within a mapping.

3. Decide which cause it is: missing colon (add it), wrapped text (indent or use a block scalar), lost comment mark (add #), missing dash (add it).

4. Reload and print the structure to confirm the lines landed where you meant.

A linter reports this as a syntax error with the same position, so it does not help with the location beyond what the parser says. What helps is an editor with syntax highlighting for YAML: a key is highlighted in one color and plain text in another, so a sentence in the "key" color, with no colon, stands out. If your highlighting shows the whole rest of the file in a strange color after a certain line, the problem starts at that line.

Why the error message says "simple key"

YAML distinguishes simple keys (a single-line scalar followed by a colon) from complex keys (introduced by ? and allowed to span lines). Almost all keys are simple. The "simple" in the message is the scanner telling you which rule it was applying: it assumed a simple key, and the rules for a simple key include a limit of 1024 characters and one line. A very long single-line key, or one that wraps, triggers related messages. Real files rarely need complex keys, and if you find yourself using one, a restructure is probably in order.

Related reading

The cluster hub is fixing YAML errors that make no sense. Sibling errors: mapping values are not allowed here, did not find expected key and found character that cannot start any token. Simple keys are defined in the YAML 1.2.2 specification, section 7.4.2 and the scanner design in the libyaml documentation. Check a repaired file in the YAML to JSON tool.

When the missing colon is not the problem

An earlier quote is unclosed. If a double quote opened and never closed, the following lines are inside the string, and the error appears far from the real mistake. Look for the unmatched quote, which gives its own message when the stream ends.

The file is not YAML. A Markdown or plain text file saved with a .yaml extension fails this way on its first prose line.

The text is a template. Files with {{ ... }} placeholders are not valid YAML until rendered. Lint the rendered output.

You meant a multi-document stream. A line of three dashes separates documents, and one with a typo (two dashes) is just text and triggers this error.