CircleCI "Build error: Unable to parse YAML"

By Daniel Zoghalchali·Latchkey

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

What this error means

The pipeline is not created. CircleCI shows "Build error: Unable to parse YAML" pointing at a line and column, and no jobs run. It reproduces every push until the file is fixed.

Build error: Unable to parse YAML
while scanning for the next token
found character that cannot start any token
 in 'string', line 7, column 1

Common causes

Wrong indentation or a tab character

YAML forbids tabs for indentation and nests by spaces. A misaligned key or a single tab makes the parser reject the document.

Unquoted special characters

A value starting with *, &, @, {, [, or containing a colon-space, reads as YAML structure unless quoted.

How to fix it

Validate locally and fix the line

The CLI parses offline and prints the exact failing line.

circleci config validate .circleci/config.yml

Remove tabs and quote special values

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

How to prevent it

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

Frequently asked questions

Related guides

References

• GitHub Actions documentation