GitLab "Invalid YAML" / "did not find expected key" in .gitlab-ci.yml

Before GitLab even checks CI keywords, the YAML parser must read the file. A structural YAML error - indentation, a tab, or an unquoted colon - stops it at the parsing stage.

What this error means

The pipeline fails to create with a raw YAML parser message ("did not find expected key", "mapping values are not allowed here", "Invalid configuration format") rather than a CI-specific one. It points at a line and column.

Pipeline Editor

Invalid configuration format
(<unknown>): did not find expected key while parsing a block mapping at line 8 column 3

Common causes

Inconsistent indentation or a tab

YAML is whitespace-sensitive and forbids tabs for indentation. One stray tab or a misaligned key under a job breaks the block mapping.

Unquoted special characters

A value containing a leading *, &, {, [, : followed by a space, or a % confuses the parser. Wrapping it in quotes makes it a plain string.

How to fix it

Fix indentation and remove tabs

Open the file at the reported line and column.
Convert any tabs to spaces; YAML mappings nest by two spaces consistently.
Make sure every job key (script, stage, rules) aligns under its job at the same depth.

Quote values with special characters

Wrap commands and values that start with or contain YAML metacharacters.

.gitlab-ci.yml

script:
  - "echo build: started"   # colon+space needs quoting
  - 'curl -H "Accept: application/json" https://api.example.com'

How to prevent it

Configure your editor to insert spaces, never tabs, in YAML.
Add a YAML linter (yamllint) step before the CI lint.
Use the Pipeline Editor, which surfaces parse errors as you type.