CircleCI "Unable to parse YAML" - Fix config.yml Syntax

By Kaveh Alemi·Latchkey

CircleCI could not even parse .circleci/config.yml as YAML. The pipeline fails before any job is scheduled - the file is malformed, usually from indentation, a tab character, or an unquoted special character.

What this error means

The pipeline is not created at all. CircleCI shows a red "Unable to parse YAML" banner on the project, pointing at a line and column, and no jobs run. It reproduces every push until the file is fixed.

CircleCI UI

Unable to parse YAML
mapping values are not allowed here
 in 'string', line 12, column 9:
       image: cimg/node:20.11
            ^

Common causes

Wrong indentation or a tab character

YAML is whitespace-sensitive and forbids tabs for indentation. A misaligned key or a single tab makes the parser reject the document with "mapping values are not allowed here" or "found character that cannot start any token".

Unquoted special characters

Values that start with *, &, {, [, @, or contain a colon followed by a space read as YAML syntax. An unquoted image: foo:bar: baz or a leading * must be wrapped in quotes.

A mapping where a list was expected (or vice versa)

steps: and jobs: have a fixed shape. Writing a key/value where CircleCI expects a - list item (or the reverse) produces a parse error before schema validation.

How to fix it

Validate locally with the CircleCI CLI

The CLI parses and validates the config offline and prints the exact failing line.

Terminal

circleci config validate .circleci/config.yml

Fix indentation and remove tabs

Open the file at the reported line and column.
Replace any tab characters with spaces (2 spaces per level is the CircleCI convention).
Quote any value containing a colon-space, or starting with *, &, @, {, or [.

Lint YAML in pre-commit

Catch malformed YAML before it reaches CircleCI.

Terminal

yamllint .circleci/config.yml

How to prevent it

Run circleci config validate in a pre-commit hook or a lint job.
Configure your editor to insert spaces, not tabs, and show whitespace.
Quote string values that contain colons or start with YAML indicator characters.

Frequently asked questions

Why does it say "mapping values are not allowed here"?

That generic YAML message means a colon appeared where the parser did not expect a new key - usually an unquoted value containing : , or a line indented one level too shallow so it reads as a sibling key.

References

GitHub Actions documentation