CircleCI "mapping values are not allowed here" YAML parse error

By Daniel Zoghalchali·Latchkey

CircleCI could not parse .circleci/config.yml as YAML. "mapping values are not allowed here" means the parser hit a key: value colon where it expected a scalar, almost always from wrong indentation or an unquoted colon inside a value.

What this error means

The pipeline never starts. CircleCI shows "Unable to parse YAML" with a line and column, followed by "mapping values are not allowed here".

Unable to parse YAML
while scanning a simple key
 in 'string', line 12, column 7:
      run: echo "deploy: started"
      ^
could not find expected ':'
mapping values are not allowed here
 in 'string', line 12, column 12

Common causes

An unquoted colon inside a value

A run command or string contains : (like echo "deploy: started") at the top level, so YAML reads it as a nested mapping key.

Wrong indentation under a step

A key is indented to a level YAML cannot attach to its parent, so the colon appears where only a scalar is allowed.

How to fix it

Quote values that contain a colon

1. Open the line/column CircleCI prints.
2. Wrap any value containing : in quotes, or use the block scalar form |.
3. Re-validate locally before pushing.

steps:
  - run: 'echo "deploy: started"'
  # or
  - run:
      command: |
        echo "deploy: started"

Validate the YAML with the CLI

Run circleci config validate to catch the parse error before it reaches the pipeline.

circleci config validate

How to prevent it

• Quote any string value that contains a colon followed by a space.
• Use block scalars (|) for multi-line shell commands.
• Run circleci config validate in a pre-push hook.

Frequently asked questions

Related guides

References

• GitHub Actions documentation