Docker Compose "yaml: line N: ..." Parse Error in CI

Compose could not parse the file. A yaml: line N: ... error is a raw YAML syntax problem - wrong indentation, a tab instead of spaces, a missing colon, or a mis-nested key - before Compose even validates the schema.

What this error means

A docker compose up/config fails with yaml: line N: did not find expected key, mapping values are not allowed here, or found character that cannot start any token. The line number points near the broken indentation.

yaml: line 8: did not find expected key
# services:
#   api:
#     image: myorg/api:1.4.2
#      ports:        <- over-indented, breaks the mapping

Common causes

Inconsistent indentation

YAML is indentation-sensitive; an extra/missing space or a tab character breaks the mapping at that line.

A missing colon or mis-nested key

A key without its colon, or a value placed where a key is expected, produces mapping values are not allowed here.

Tabs used for indentation

YAML forbids tabs for indentation; a tab yields found character that cannot start any token.

How to fix it

Validate the file and fix the flagged line

Run config to surface the exact line, then correct the indentation.

docker compose config
# fix indentation to two spaces, no tabs, on the flagged line

Lint YAML in CI

Add a YAML lint step so syntax errors fail fast and clearly.

- run: yamllint docker-compose.yml
- run: docker compose config -q

How to prevent it

• Use spaces, not tabs, with consistent indentation.
• Run docker compose config -q as a pre-flight check in CI.
• Lint compose YAML with yamllint in the pipeline.

Related guides