Maaz Zindani

Loading the index…

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

docker-compose.yml fails with expected block end but found block mapping start

Errorwhile parsing a block mapping ... expected <block end>, but found '<block mapping start>'

Short answer

This comes from the YAML parser, not from Compose rules. A line is indented differently from its siblings, or a value is written so the parser starts a new mapping where it expected the end of a block. Fix the indentation, remove tabs and quote values that contain a colon followed by a space.

  • Applies to Docker Compose v2, YAML 1.2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Let Compose parse the file without starting anything. The error names the line; look one or two lines above it, because the real mistake is usually the line before.

    docker compose config --quiet
  2. 2Match what you see, then jump to its fix

    1. 1The reported line sits just under a key whose children are not alignedSibling keys are indented by different amountsFix
    2. 2A line starts with a tab (cat -A shows it as ^I)A tab character is used for indentationFix
    3. 3The YAML parses in an editor but docker compose config still stops at a keyThe file is not valid once Compose reads it as the modelFix

What does the error look like?

  • while parsing a block mapping ... expected <block end>, but found '<block mapping start>'

Cause 1 of 3

Sibling keys are indented by different amounts

1Check

The YAML specification says all sibling nodes must use the exact same indentation level. One extra or missing space in a service block breaks it.

cat -A docker-compose.yml

2Fix

Align every key of one block to the same column and indent children by a consistent step (two spaces is the convention).

services:
  web:
    image: nginx:1.27
    ports:
      - "8080:80"
  db:
    image: postgres:17

3Verify

The file parses and prints the merged configuration.

docker compose config --quiet && echo OK

Confirmed by yaml.org

Did this fix it?

Cause 2 of 3

A tab character is used for indentation

1Check

YAML forbids tabs in indentation. Many editors insert them silently, especially when you paste from a terminal or a web page.

grep -n -P '\t' docker-compose.yml

2Fix

Replace each tab with spaces, and set your editor to indent YAML with spaces.

expand -t 2 docker-compose.yml > docker-compose.fixed.yml
mv docker-compose.fixed.yml docker-compose.yml

3Verify

grep finds no tab and the parser accepts the file.

grep -c -P '\t' docker-compose.yml
docker compose config --quiet && echo OK

Confirmed by yaml.org

Did this fix it?

Cause 3 of 3

The file is not valid once Compose reads it as the model

1Check

docker compose config parses, resolves and renders the file, and validates it unless you disable the consistency check. Run it again, with the full output this time, and compare the key it names to the Compose reference.

docker compose config

2Fix

Correct the named key to the shape the Compose file reference allows, then run the command again.

docker compose config --quiet

3Verify

The command prints nothing and exits with code 0.

docker compose config --quiet; echo $?

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Run docker compose config --quiet before every up, and in CI.
  • Set your editor to show whitespace and to indent YAML with spaces.
  • Use a YAML-aware editor mode that highlights mixed indentation.

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

docker compose says invalid compose project

docker compose up or config stops with a message that ends in invalid compose project

invalid compose project is a wrapper: the real reason is in the text before it.

2 causes, each with a fix

Next step

Want this handled for good?

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