How to fix yaml: line X: did not find expected key in Docker

DockerBEGINNERMEDIUM

This YAML parsing error occurs when Docker Compose cannot interpret your docker-compose.yml file due to malformed syntax. The most common causes are incorrect indentation, tabs instead of spaces, or invisible characters from copy-pasting. The fix usually involves correcting the whitespace at the line number indicated in the error.

What this error means

When Docker Compose displays "yaml: line X: did not find expected key," it means the YAML parser encountered unexpected syntax while reading your docker-compose.yml file. YAML is a whitespace-sensitive format, and even small formatting errors can break parsing. The "did not find expected key" message specifically indicates that the parser was expecting a key-value pair (like `image: nginx`) but found something else instead. This often happens when: - A line has incorrect indentation, breaking the expected structure - A key is missing its colon or value - There's a tab character where spaces are required - Invisible characters from copy-pasting are present in the file The line number in the error message points to where the parser got confused, though the actual problem may be on a previous line that set up an incorrect context.

How to fix "yaml: line X: did not find expected key"

1Locate the problematic line

The error message includes a line number. Open your docker-compose.yml and navigate to that line:

bash

# View the file with line numbers
cat -n docker-compose.yml

# Or use a text editor that shows line numbers
code docker-compose.yml
nano -l docker-compose.yml
vim docker-compose.yml

Note that the actual problem might be on a line before the reported line number, as YAML errors can cascade.

2Check for tabs vs spaces

YAML does not allow tabs for indentation - only spaces are valid. Find and replace any tabs:

Check for tabs:

bash

# Show tabs as ^I
cat -A docker-compose.yml | head -20

# Find lines with tabs
grep -n $'\t' docker-compose.yml

Replace tabs with spaces:

bash

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

# Using expand command
expand -t 2 docker-compose.yml > temp.yml && mv temp.yml docker-compose.yml

In vim:

bash

:set expandtab
:retab

3Verify proper indentation

YAML uses consistent indentation (typically 2 spaces) to define structure. All items at the same level must have identical indentation:

Correct structure:

yaml

version: '3.8'
services:          # No indent - root level
  web:             # 2 spaces - service level
    image: nginx   # 4 spaces - property level
    ports:         # 4 spaces - same as image
      - "8080:80"  # 6 spaces - list item
    environment:
      - NODE_ENV=production

Common mistakes:

yaml

# WRONG - services indented after version
version: '3.8'
  services:        # Should have no indent

# WRONG - inconsistent indentation
services:
  web:
    image: nginx
   ports:          # 3 spaces instead of 4
      - "8080:80"

4Add missing spaces after colons and dashes

YAML requires a space after colons in key-value pairs and after dashes in list items:

Fix key-value pairs:

yaml

# WRONG
image:nginx
container_name:myapp

# CORRECT
image: nginx
container_name: myapp

Fix list items:

yaml

# WRONG
ports:
  -8080:80
  -443:443

# CORRECT
ports:
  - 8080:80
  - 443:443

Even environment variables need proper spacing:

yaml

# WRONG
environment:
  -NODE_ENV=production

# CORRECT
environment:
  - NODE_ENV=production

5Remove invisible characters

Copy-pasting from websites, PDFs, or documentation can introduce invisible Unicode characters that break YAML parsing:

Detect invisible characters:

bash

# Show all non-printable characters
cat -v docker-compose.yml | head -20

# Check for specific Unicode issues
file docker-compose.yml
# Should show: "ASCII text" or "UTF-8 Unicode text"

Fix by retyping or cleaning:

bash

# Remove non-ASCII characters (be careful with intentional Unicode)
LC_ALL=C tr -cd '\11\12\15\40-\176' < docker-compose.yml > clean.yml
mv clean.yml docker-compose.yml

# Or use iconv to clean up
iconv -f utf-8 -t ascii//TRANSLIT docker-compose.yml > clean.yml

The safest approach is often to manually retype the problematic line.

6Validate with docker compose config

Use Docker Compose's built-in validation to check your file:

bash

# Validate and show parsed config
docker compose config

# Or with older docker-compose
docker-compose config

If the file is valid, this command outputs the fully parsed and normalized configuration. If there are errors, it shows exactly what's wrong.

Using online validators:
You can also paste your YAML into validators like:
- yamllint.com
- codebeautify.org/yaml-validator

These tools often provide more detailed error messages about what's wrong.

7Use binary search to isolate the problem

When the error is hard to find, use a divide-and-conquer approach:

yaml

# Start with minimal valid file
version: '3.8'
services:
  web:
    image: nginx

Then add sections back gradually:

1. Run docker compose config after each addition
2. When it breaks, the last addition contains the problem
3. Comment out half of that section
4. Keep narrowing down until you find the exact line

yaml

# Use comments to disable sections
services:
  web:
    image: nginx
    # ports:
    #   - "8080:80"
    # environment:
    #   - NODE_ENV=production

8Check dictionary vs list syntax for environment variables

Environment variables can be specified two ways, and mixing them incorrectly causes errors:

List syntax (with dashes):

yaml

environment:
  - NODE_ENV=production
  - DEBUG=false
  - PORT=3000

Dictionary syntax (key-value pairs):

yaml

environment:
  NODE_ENV: production
  DEBUG: "false"
  PORT: "3000"

WRONG - mixing both:

yaml

# This causes "did not find expected key"
environment:
  - NODE_ENV=production
  DEBUG: false         # Can't mix list and dict

Pick one style and use it consistently within each environment block.

How to fix yaml: line X: did not find expected key in Docker

What this error means

Typical symptoms

Common causes

How to fix "yaml: line X: did not find expected key"

Advanced notes

Related errors

Official resources & further reading