Compose says a YAML value must be a mapping
must be a mappingShort answer
A mapping is a block of key: value lines. The error means Compose found a list, a string or an empty value where the file format needs key: value pairs. Run docker compose config to get the line, then compare that key with the forms the Compose reference allows.
Fix it fast
1Find out which cause you have
Let Compose validate the file. It stops at the first invalid key and names it, so fix that one and run it again.
docker compose config --quiet2Match what you see, then jump to its fix
What does the error look like?
must be a mappinga service or key in docker-compose.yml fails validation right after a small editdocker compose config stops at a key and names the line
Cause 1 of 2
environment or labels mix the list form and the map form
1Check
These two keys accept either a map (KEY: value) or a list of KEY=value strings. A list item written as KEY: value, or a map entry written with a dash, is a mix.
grep -n -A4 "environment:" docker-compose.yml2Fix
Use one form for the whole key.
environment:
RACK_ENV: development
SHOW: "true"
# or
# environment:
# - RACK_ENV=development
# - SHOW=true3Verify
Validate again.
docker compose config --quiet && echo okConfirmed by docs.docker.com
Cause 2 of 2
build, depends_on or networks use the wrong shape
1Check
build is a string or a mapping with context. depends_on is a list of names or a mapping with condition. networks is a list or a mapping. Options such as condition or aliases need the mapping form, with the keys indented under the name.
grep -n -B1 -A4 "depends_on:" docker-compose.yml2Fix
Write the long form as nested key: value lines under the service name.
services:
api:
build:
context: backend
depends_on:
db:
condition: service_healthy3Verify
Validate again.
docker compose config --quiet && echo okConfirmed by docs.docker.com
How do I stop it coming back?
- Run docker compose config --quiet in an editor hook or in CI after every change to the file.
- Pick one form (map or list) per key across the whole file.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
Compose rejects the top-level name: key in docker-compose.yml
You might be seeing this error because you're using the wrong Compose file version.
A top-level name: sets the Compose project name, but only the Compose Specification tools read it.
3 causes, each with a fixServers
apk cannot find py-pip in an Alpine Docker image
py-pip (no such package):
On current Alpine releases there is no package called py-pip.
2 causes, each with a fixServers
ng serve runs in the container but localhost:4200 does not open
The browser cannot open localhost:4200 although ng serve is running in the container
ng serve listens on localhost by default, which inside a container is the container itself.
3 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
AH00558: Apache in Docker cannot reliably determine its fully qualified domain name
Set the 'ServerName' directive globally to suppress this message
AH00558 is a warning, not a crash.
2 causes, each with a fixServers
Apache in a Docker container logs AH01114 when it proxies to a backend
AH01114: HTTP: failed to make connection to backend: api
Apache's proxy worker could not open a connection to the address in ProxyPass.
5 causes, each with a fix