CircleCI "Unexpected argument" / "mapping values not allowed"

By Kaveh Alemi·Latchkey

CircleCI hit a key or value where it expected something else - an unexpected argument to a step, or a YAML "mapping values are not allowed here" from an unquoted colon or misindented key.

What this error means

Validation fails with "Unexpected argument" naming an extra/unknown key, or "mapping values are not allowed here" pointing at a line and column. The pipeline does not start.

mapping values are not allowed here
 in 'string', line 14, column 18:
       run: echo build: done
                       ^

Common causes

Unquoted colon-space in a value

A run: value containing : (for example echo build: done) reads as a new mapping. Quote the whole command so it stays a scalar.

Unexpected/extra argument to a step or job

Passing a key a step or orb command does not accept ("Unexpected argument") fails validation - usually a typo or a parameter that does not exist.

How to fix it

Quote values containing a colon

steps:
  - run:
      name: Print status
      command: 'echo build: done'   # quote the colon-space value

Remove or correct the unexpected key

1. Check the step/command/orb docs for the exact parameter names it accepts.
2. Delete keys that are typos or do not belong at that position.
3. Run circleci config validate to confirm the argument is now accepted.

How to prevent it

• Quote any value that contains a colon followed by a space.
• Reference step and orb parameter names exactly.
• Validate config locally before pushing.

Frequently asked questions

Related guides

References

• GitHub Actions documentation