How to fix ERROR: yaml.parser.ParserError: while parsing a block mapping in Docker

The error message tells you where the parser failed. Start by looking at that line and the lines around it:

# Replace LINE_NUMBER with the number from your error
sed -n 'LINE_NUMBER-3,LINE_NUMBER+3p' docker-compose.yml

# Or view with line numbers
cat -n docker-compose.yml | sed -n 'LINE_NUMBER-3,LINE_NUMBER+3p'

Important: The actual mistake is often on the line *before* the reported line number. The parser reports where it detected the problem, which may be after the actual error.

Look for:
- Lines that seem misaligned compared to siblings
- Missing spaces after colons
- Keys that appear at the wrong indentation level

YAML requires spaces for indentation - tabs are forbidden. Detect tabs in your file:

# Show all characters including tabs (^I)
cat -A docker-compose.yml

# Or search for tab characters
grep -P '\t' docker-compose.yml

If you find tabs, convert them to spaces:

# Convert tabs to 2 spaces
sed -i 's/\t/  /g' docker-compose.yml

# Or use expand for more control
expand -t 2 docker-compose.yml > docker-compose.yml.new
mv docker-compose.yml.new docker-compose.yml

Editor configuration to prevent this:

VS Code (settings.json):

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

Ensure your docker-compose.yml has the correct top-level structure:

# Modern format (Docker Compose V2+)
services:
  web:
    image: nginx

# Legacy format (requires version)
version: "3.8"
services:
  web:
    image: nginx

Common structural mistakes:

# WRONG - services not indented under root
web:
  image: nginx

# WRONG - missing services key
version: "3"
web:
  image: nginx

# CORRECT
services:
  web:
    image: nginx

Check that all your services are nested under the services: key with consistent 2-space indentation.

All elements at the same nesting level must have identical indentation. Standard Docker Compose uses 2-space indentation:

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

# CORRECT - consistent 2-space indentation
services:          # Level 0 (no indent)
  web:             # Level 1 (2 spaces)
    image: nginx   # Level 2 (4 spaces)
    ports:         # Level 2 (4 spaces)
      - "8080:80"  # Level 3 (6 spaces)

To visualize indentation:

# Show whitespace characters
cat -A docker-compose.yml

# Count leading spaces per line
awk '{match($0, /^ */); print NR": "RLENGTH" spaces: "$0}' docker-compose.yml

Use your editor's "show whitespace" feature to see indentation levels clearly.

Copy-pasting from websites, documentation, or PDFs often introduces invisible problematic characters:

- Smart quotes: " and " instead of straight "
- Non-breaking spaces: Different from regular spaces
- BOM marker: Invisible character at file start

Detect non-ASCII characters:

# Find lines with non-ASCII characters
grep -nP '[^\x00-\x7F]' docker-compose.yml

# Check for BOM at start of file
file docker-compose.yml
# Should say "ASCII text" not "UTF-8 Unicode (with BOM)"

# View hex dump of first few bytes
xxd docker-compose.yml | head -5

Remove problematic characters:

# Remove BOM if present
sed -i '1s/^\xEF\xBB\xBF//' docker-compose.yml

# Convert smart quotes to regular quotes
sed -i 's/[""]/"/g; s/[''']/'''/g' docker-compose.yml

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

Best approach: Manually retype the problematic section rather than trying to find invisible characters.

Use yamllint for detailed YAML validation with more helpful 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 feedback about:
- Indentation problems
- Line length issues
- Trailing spaces
- Key ordering
- Document start markers

Online validators (paste your YAML content):
- https://www.yamllint.com/
- https://yamlchecker.com/
- https://codebeautify.org/yaml-validator

Note: Generic YAML validators might pass a file that Docker Compose still rejects. The Docker Compose schema has additional requirements beyond basic YAML syntax.

Docker Compose includes a built-in validation command:

# Validate and display resolved configuration
docker compose config

# Quiet mode - only shows errors
docker compose config --quiet

# Specify a different file
docker compose -f my-compose.yml config

If the YAML is valid, this outputs the fully resolved configuration with all variables substituted. If there's an error, it provides detailed information.

When other methods fail, use the binary search approach:

1. Create a minimal working file:

services:
  test:
    image: alpine

2. Verify it works: docker compose config

3. Add sections from your broken file one at a time

4. Run docker compose config after each addition

5. When it breaks, you've found the problematic section

If you cannot locate the issue, recreating the file often resolves hidden character problems:

# Back up original
cp docker-compose.yml docker-compose.yml.backup

# Create new file in your editor (not copy-paste)
# Type out the configuration manually

When recreating:
1. Use a code editor with YAML support (VS Code, Sublime Text)
2. Enable "show whitespace" characters
3. Type each line manually instead of copying
4. Use 2 spaces consistently for each indentation level
5. Validate frequently with docker compose config

Template to start with:

services:
  app:
    image: your-image:tag
    ports:
      - "8080:80"
    environment:
      - NODE_ENV=production
    volumes:
      - ./data:/app/data

Build up from this working template, adding your specific configuration piece by piece.