GitLab "yaml invalid: did not find expected key"

By Daniel Zoghalchali·Latchkey

Before GitLab checks any CI keyword, the YAML parser must read the document. "did not find expected key" means the block mapping broke - usually indentation, a stray tab, or a misaligned key.

What this error means

Pipeline creation fails with a raw parser message rather than a CI-specific one, citing a line and column. Nothing runs until the structural YAML error is fixed.

yaml invalid:
(<unknown>): did not find expected key while parsing a block mapping at line 9 column 5

Common causes

Inconsistent indentation or a tab

YAML nests by spaces and forbids tabs for indentation. One misaligned key under a job, or a single tab, breaks the surrounding block mapping.

A key not aligned with its siblings

If script sits one space deeper or shallower than stage under the same job, the parser cannot tell where the mapping continues and reports the missing key.

How to fix it

Fix indentation at the reported line

1. Open the file at the cited line and column.
2. Convert any tabs to spaces; keep two-space nesting consistent.
3. Align every job key (script, stage, rules) at the same depth under its job.

Quote values with special characters

A colon-space, or a leading */&/[/{, inside an unquoted scalar is read as YAML structure - quote it.

script:
  - "echo deploy: started"   # colon+space must be quoted
  - '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 yamllint step before the CI lint to catch parse errors early.
• Use the Pipeline Editor, which surfaces parse errors as you type.

Frequently asked questions

Related guides

References

• GitHub Actions documentation