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

What this error means

The "yaml: line X: mapping values are not allowed in this context" error is a YAML parsing error that indicates the parser encountered a colon (`:`) in an unexpected location. In YAML, colons define key-value mappings, and the parser found one where it wasn't syntactically valid. This error almost always stems from whitespace problems. YAML is extremely sensitive to indentation - unlike JSON or XML, whitespace is part of the syntax. The error message tells you the line number where parsing failed, but the actual problem is often on the previous line or involves invisible characters. Common scenarios that trigger this error: 1. **Mixed tabs and spaces**: YAML requires spaces for indentation. A single tab character will cause this error. 2. **Missing space after colon**: Key-value pairs require a space after the colon (`key: value`, not `key:value`). 3. **Inconsistent indentation**: All items at the same level must have identical indentation. 4. **Copy-paste artifacts**: Text copied from websites or PDFs often contains hidden Unicode characters like "smart quotes" or non-breaking spaces. The YAML parser reads your file line by line, building a tree structure based on indentation. When it encounters something that breaks this structure - like a colon appearing where it expects a value - it reports this error.

Typical symptoms

• Running `docker-compose up` or `docker compose up` shows 'mapping values are not allowed in this context'
• The error includes a specific line number like 'yaml: line 5:'
• Docker Compose fails immediately without starting any services
• The YAML file works after retyping sections manually
• Error appears after copying docker-compose.yml content from a website or documentation
• File validates on some YAML validators but Docker Compose still rejects it
• CI/CD pipeline fails with YAML parsing errors

Common causes

1. Using tab characters instead of spaces for indentation (most common cause)
2. Missing space after a colon in a key-value pair (e.g., `image:nginx` instead of `image: nginx`)
3. Inconsistent indentation levels (mixing 2-space and 4-space indentation)
4. Hidden Unicode characters from copy-paste (smart quotes, en-dashes, non-breaking spaces)
5. Incorrect indentation after a multiline value or block scalar
6. Colons in unquoted string values (e.g., `command: echo: hello` instead of `command: "echo: hello"`)
7. Wrong nesting level for a key (item indented too much or too little)

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

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

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

# 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

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

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

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

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

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

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

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

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

# 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

# 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

# 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"

# 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`)"

# Install yamllint
pip install yamllint

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

# Run validation
yamllint docker-compose.yml

# Docker Compose config validation
docker compose config

# Validate and show resolved config
docker compose config

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

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

Advanced notes

{
  "[yaml]": {
    "editor.insertSpaces": true,
    "editor.tabSize": 2,
    "editor.autoIndent": "keep",
    "editor.formatOnSave": false
  },
  "yaml.validate": true,
  "yaml.schemaStore.enable": true
}

# WRONG - YAML interprets this as key:value
environment:
  DEBUG: true    # Becomes string "true" - might not be what you want
  PORT: 3000     # Becomes integer 3000

# BETTER - explicit strings
environment:
  DEBUG: "true"
  PORT: "3000"

# BEST - list format (unambiguous)
environment:
  - DEBUG=true
  - PORT=3000

# WRONG - bare colon in unquoted string
command: python manage.py runserver 0.0.0.0:8000

# CORRECT - quoted
command: "python manage.py runserver 0.0.0.0:8000"

# ALSO CORRECT - using list format
command: ["python", "manage.py", "runserver", "0.0.0.0:8000"]

Frequently asked questions

What does "yaml: line X: mapping values are not allowed in this context" mean?

The "yaml: line X: mapping values are not allowed in this context" error is a YAML parsing error that indicates the parser encountered a colon (:) in an unexpected location. In YAML, colons define key-value mappings, and the parser found one where it wasn't syntactically valid. This error almost always stems from whitespace problems.

How do I fix "yaml: line X: mapping values are not allowed in this context"?

The 'mapping values are not allowed in this context' error occurs when Docker Compose fails to parse your YAML file due to indentation issues, tabs instead of spaces, missing spaces after colons, or hidden Unicode characters. This is one of the most common YAML syntax errors.

What causes "yaml: line X: mapping values are not allowed in this context"?

Using tab characters instead of spaces for indentation (most common cause) Missing space after a colon in a key-value pair (e.g., image:nginx instead of image: nginx) Inconsistent indentation levels (mixing 2-space and 4-space indentation)

Is the "yaml: line X: mapping values are not allowed in this context" error serious?

It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Related errors

• ERROR: Invalid interpolation format

  How to fix 'Invalid interpolation format' in Docker Compose

  LOW

• dependency condition 'service_healthy' was never satisfied

  How to fix 'dependency condition service_healthy was never satisfied' in Docker Compose

  MEDIUM

• ERROR: services.web Additional property invalid is not allowed

  How to fix 'Additional property invalid is not allowed' in Docker Compose

  LOW

• ERROR: Service 'web' has an invalid healthcheck definition

  How to fix 'Service has an invalid healthcheck definition' in Docker Compose

  MEDIUM

• WSL 2 requires an update to its kernel component

  How to fix 'WSL 2 requires an update to its kernel component' in Docker

  MEDIUM

• dial tcp: i/o timeout

  How to fix 'dial tcp: i/o timeout' in Docker

  MEDIUM

Official resources & further reading

• 📚Docker Official Documentation
• 📖
  Docker Compose file reference - Docker Docs(Official Docs)
• 💬
  How to fix 'mapping values are not allowed in this context' error - Stack Overflow(Stack Overflow)
• 💬
  yml docker-compose error mapping values are not allowed here - Stack Overflow(Stack Overflow)
• 🐙
  mapping values are not allowed in this context while running service - GitHub Issue(GitHub)
• 💬
  Error yaml: mapping values are not allowed - Docker Forums(Stack Overflow)
• 📝
  100 Common Docker Errors & Solutions - DEV Community