Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Compose says a YAML value must be a mapping

Errormust be a mapping

Short 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.

  • Applies to Docker Compose 2.40, Compose Specification
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 --quiet
  2. 2Match what you see, then jump to its fix

    1. 1the error names an environment or labels keyenvironment or labels mix the list form and the map formFix
    2. 2the error names build, depends_on or networksbuild, depends_on or networks use the wrong shapeFix

What does the error look like?

  • must be a mapping
  • a service or key in docker-compose.yml fails validation right after a small edit
  • docker 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.yml

2Fix

Use one form for the whole key.

environment:
  RACK_ENV: development
  SHOW: "true"
# or
# environment:
#   - RACK_ENV=development
#   - SHOW=true

3Verify

Validate again.

docker compose config --quiet && echo ok

Confirmed by docs.docker.com

Did this fix it?

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.yml

2Fix

Write the long form as nested key: value lines under the service name.

services:
  api:
    build:
      context: backend
    depends_on:
      db:
        condition: service_healthy

3Verify

Validate again.

docker compose config --quiet && echo ok

Confirmed by docs.docker.com

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.