Docker Compose "mapping values are not allowed" - Fix YAML

Compose could not parse the YAML structure of the file. Almost always indentation: a key at the wrong depth, a tab, or a colon where YAML did not expect one.

What this error means

docker compose up/config fails before doing anything with a YAML structure error like mapping values are not allowed in this context or services must be a mapping, naming a line.

docker compose output

yaml: line 9: mapping values are not allowed in this context
# or: services.api must be a mapping

Common causes

Wrong indentation or a tab character

YAML is whitespace-sensitive and forbids tabs. A misaligned key or a tab makes the parser see an invalid structure at the reported line.

A stray colon or missing list/map nesting

An unquoted value containing a colon, or a service body that is a scalar where a mapping is expected, breaks parsing.

How to fix it

Validate the structure with compose config

Use docker compose config to parse and normalize the file; it points at the bad line.

Terminal

docker compose config            # parses + prints the merged config
# or validate YAML alone:
python -c "import yaml,sys; yaml.safe_load(open('docker-compose.yml'))"

Fix indentation and quote risky values

Replace any tabs with spaces and align keys to consistent 2-space depth.
Quote values that contain colons (e.g. image refs with ports, time-like strings).
Ensure each service body is a mapping (key: value pairs), not a bare scalar.

How to prevent it

Lint compose files in CI with docker compose config before use.
Configure editors to use spaces, not tabs, for YAML.
Quote values that contain colons or special characters.