How to fix yaml: line X: mapping values are not allowed in this context in Docker

The error message includes a line number. Start by examining that line and the line before it:

# Show lines around the error (replace 5 with your error line number)
sed -n '3,7p' docker-compose.yml

Important: The actual issue is often on the line before the reported line number. The parser reports where it detected the problem, not necessarily where the mistake is.

Look for:
- Missing spaces after colons
- Keys that look misaligned
- Values that contain colons without quotes

YAML requires spaces for indentation - tabs are not allowed. Check if your file contains tabs:

# Show tabs as ^I characters
cat -A docker-compose.yml

If you see ^I characters, those are tabs that need to be converted to spaces.

Convert tabs to spaces:

# Using sed (creates backup)
sed -i.bak 's/\t/  /g' docker-compose.yml

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

Configure your editor to use spaces:

- VS Code: Add to settings.json:

"[yaml]": {
    "editor.insertSpaces": true,
    "editor.tabSize": 2
  }

- Vim: Add to .vimrc:

autocmd FileType yaml setlocal ts=2 sts=2 sw=2 expandtab

Every key-value pair in YAML needs a space after the colon. This is wrong:

# WRONG - no space after colon
services:
  web:
    image:nginx
    ports:
      -"8080:80"

This is correct:

# CORRECT - space after each colon
services:
  web:
    image: nginx
    ports:
      - "8080:80"

Search for missing spaces:

# Find lines with colon immediately followed by non-space/newline
grep -n ':[^ $]' docker-compose.yml | grep -v '://'

The grep -v '://' excludes URLs which legitimately have colons without spaces.

All keys at the same level must have identical indentation. Check your file structure:

# WRONG - inconsistent indentation
services:
  web:
    image: nginx
     ports:        # Extra space!
      - "8080:80"

# CORRECT - consistent 2-space indentation
services:
  web:
    image: nginx
    ports:
      - "8080:80"

Use a visual approach to check alignment:

# Show line numbers and content
cat -n docker-compose.yml

Or use your editor's "show whitespace" feature to visualize indentation levels.

Standard Docker Compose indentation:
- Top-level keys (services:, networks:, volumes:): 0 spaces
- Service names: 2 spaces
- Service properties (image:, ports:): 4 spaces
- Nested values: 6+ spaces

Copy-pasting from websites or PDFs often introduces invisible Unicode characters that break YAML parsing:

- Smart quotes: "text" or 'text' instead of "text" or 'text'
- En-dash: - (U+2013) instead of - (hyphen U+002D)
- Non-breaking spaces: (U+00A0) instead of regular space

Find problematic characters:

# Show non-ASCII characters with line numbers
grep -nP '[^\x00-\x7F]' docker-compose.yml

# Or use hexdump to see byte values
hexdump -C docker-compose.yml | head -50

Fix by retyping or using sed:

# Replace common smart quotes with regular quotes
sed -i "s/[""]/"/g" docker-compose.yml
sed -i "s/['']/'/g" docker-compose.yml

# Alternative: remove all non-ASCII characters
LC_ALL=C tr -cd '[:print:][:space:]' < docker-compose.yml > docker-compose.yml.clean
mv docker-compose.yml.clean docker-compose.yml

Best practice: Manually retype the section around the error line rather than trying to find invisible characters.

If a value contains a colon, it must be quoted to prevent YAML from interpreting it as a nested mapping:

# WRONG - colon in value causes parsing error
services:
  web:
    command: flask run --host=0.0.0.0:5000

# CORRECT - quoted string
services:
  web:
    command: "flask run --host=0.0.0.0:5000"

Common places where this matters:

# Environment variables with values containing colons
environment:
  - "DATABASE_URL=postgres://user:pass@host:5432/db"

# Commands with port mappings
command: ["python", "-m", "http.server", "8000:8000"]

# Labels with colons
labels:
  - "traefik.http.routers.web.rule=Host(`example.com`)"

When in doubt, quote string values that contain special characters like :, #, [, ], {, }.

Use yamllint for detailed YAML validation with better error messages:

# Install yamllint
pip install yamllint

# Or on Ubuntu/Debian
sudo apt-get install yamllint

# Run validation
yamllint docker-compose.yml

yamllint provides specific warnings about:
- Line length
- Trailing spaces
- Missing document start (---)
- Truthy values
- Indentation style

Online validators:
- https://www.yamllint.com/
- https://yamlchecker.com/

Note: A file can pass generic YAML validation but still fail Docker Compose validation. After yamllint passes, also run:

# Docker Compose config validation
docker compose config

This validates both YAML syntax and Docker Compose schema.

Docker Compose has a built-in validation command that parses your file and outputs the resolved configuration:

# Validate and show resolved config
docker compose config

# Just validate, don't output
docker compose config --quiet

If successful, this command outputs the fully resolved docker-compose.yml (with all variables substituted and defaults applied). If there's an error, it shows detailed information about what went wrong.

This is more thorough than generic YAML validators because it also checks:
- Service configuration validity
- Volume mount syntax
- Network configuration
- Environment variable substitution

Tip: If the error persists, try creating a minimal docker-compose.yml and adding sections back one at a time:

# Start with bare minimum
services:
  test:
    image: alpine
    command: echo "test"

Run docker compose config after each addition to isolate which section causes the error.