How to fix ERROR: yaml.scanner.ScannerError: while scanning a simple key in Docker

DockerBEGINNERLOWUpdated Dec 1, 2025· 295 views

The yaml.scanner.ScannerError in Docker Compose occurs when the YAML parser encounters invalid syntax, usually due to tabs instead of spaces, incorrect indentation, or missing spaces after colons. This is one of the most common Docker Compose errors and is easily fixed by validating your YAML file.

Quick fix

Fixes ERROR: yaml.scanner.ScannerError: while scanning a simple key

ERROR: yaml.scanner.ScannerError: while scanning a simple key
  in "./docker-compose.yml", line 15, column 3
  1. Check the error line number
  2. Replace tabs with spaces
  3. Validate YAML syntax online
  4. Add missing spaces after colons
docker — error
ERROR: yaml.scanner.ScannerError: while scanning a simple key
  in "./docker-compose.yml", line 15, column 3
ERROR: yaml.scanner.ScannerError: while scanning a simple key

What this error means

The `yaml.scanner.ScannerError: while scanning a simple key` error occurs when Docker Compose's YAML parser encounters invalid syntax while reading your docker-compose.yml file. YAML is extremely sensitive to formatting, and this error typically indicates a structural problem with how your file is written. The "simple key" referenced in the error refers to YAML's internal concept of a key in a key-value pair. When the parser says it's having trouble "scanning" a simple key, it means it found unexpected characters or formatting where it expected to find a valid key definition. This error is thrown by the underlying PyYAML library that Docker Compose uses to parse configuration files. Unlike JSON, YAML relies on whitespace for structure, which makes it prone to subtle formatting errors that can be difficult to spot visually.

Typical symptoms

  • Docker Compose commands fail immediately with yaml.scanner.ScannerError
  • Error message includes a line number and column pointing to the problem area
  • The same docker-compose.yml worked before a recent edit
  • Compose file copied from documentation or another source fails to parse
  • File appears correct when viewed in a text editor but still fails

Common causes

  1. Tab characters used for indentation instead of spaces (YAML strictly requires spaces)
  2. Inconsistent indentation levels (mixing 2-space and 4-space indentation)
  3. Missing space after colons in key-value pairs (e.g., "restart:always" instead of "restart: always")
  4. Hidden characters introduced when copying from PDFs, Slack, or web pages
  5. Incorrect nesting of services, volumes, or networks sections
  6. Unquoted strings containing special characters like colons or quotes

How to fix "ERROR: yaml.scanner.ScannerError: while scanning a simple key"

1Check the error line number

The error message includes the exact location of the problem. Look at the line and column numbers reported:

bash
ERROR: yaml.scanner.ScannerError: while scanning a simple key
  in "./docker-compose.yml", line 15, column 3

Open your docker-compose.yml file and navigate to that specific line to inspect the formatting around it.

2Replace tabs with spaces

YAML does not allow tab characters for indentation. Convert all tabs to spaces (typically 2 spaces per indent level).

In VS Code:
1. Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
2. Type "Convert Indentation to Spaces"
3. Select the option to convert

Using sed on Linux/Mac:

bash
sed -i 's/	/  /g' docker-compose.yml

Verify no tabs remain:

bash
grep -P '	' docker-compose.yml

If this command returns nothing, your file has no tab characters.

3Validate YAML syntax online

Use an online YAML validator to identify syntax errors:

1. Go to [YAML Lint](https://www.yamllint.com/) or [Code Beautify YAML Validator](https://codebeautify.org/yaml-validator)
2. Paste your docker-compose.yml content
3. The validator will highlight exact syntax errors

Alternatively, use the docker compose config command to validate:

bash
docker compose config

This parses the file and outputs the resolved configuration, or shows detailed error messages if parsing fails.

4Add missing spaces after colons

YAML requires a space after colons in key-value pairs. Check for lines like:

yaml
# Wrong - missing space after colon
restart:always
ports:
  -"80:80"

# Correct - space after colon
restart: always
ports:
  - "80:80"

Pay special attention to any lines you recently edited.

5Fix indentation alignment

Ensure consistent indentation throughout the file. All items at the same level must have identical indentation:

yaml
# Wrong - inconsistent indentation
services:
  web:
    image: nginx
     ports:    # Extra space causes error
      - "80:80"

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

The services, volumes, and networks top-level keys should have no indentation. Their children should be indented by 2 spaces.

6Re-type copied content

If you copied your docker-compose.yml from a PDF, Slack message, or website, hidden characters may have been introduced. The safest fix is to manually re-type the problematic section.

Alternatively, paste the content into a plain text editor first, then copy it again to your docker-compose.yml file.

Common sources of hidden characters:
- PDF documentation (often introduces special quote characters)
- Slack or Teams messages (may convert quotes to "smart quotes")
- Web pages with rich text formatting

7Install a YAML linter extension

Prevent future errors by installing a YAML linting extension in your editor:

VS Code:
- Install the "YAML" extension by Red Hat
- It provides real-time syntax highlighting and error detection

Enable the extension for Docker Compose files by adding to your VS Code settings:

json
{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/compose-spec/compose-spec/master/schema/compose-spec.json": "docker-compose*.yml"
  }
}

This provides autocomplete and validation specific to Docker Compose syntax.

Advanced notes

### Understanding YAML Parsing Errors

The PyYAML library used by Docker Compose performs a two-phase parse: first scanning tokens, then parsing the structure. The "ScannerError" indicates failure in the first phase, meaning the raw text couldn't even be tokenized into valid YAML elements.

### Debugging Complex Files

For large docker-compose files, use a divide-and-conquer approach:
1. Comment out half the file
2. Run docker compose config
3. If it passes, the error is in the commented section
4. Repeat until you isolate the problem

### Multi-file Compose Setups

When using multiple compose files with -f flags, ensure each file is valid independently:

bash
docker compose -f docker-compose.yml config
docker compose -f docker-compose.override.yml config

### Environment Variable Syntax

Environment variables in Compose files have specific quoting rules:

yaml
# These are all valid
environment:
  - DEBUG=true
  - "PORT=8080"
  - 'API_KEY=secret'

# This is problematic (nested quotes)
environment:
  - API_URL="http://example.com"  # The quotes become part of the value

Frequently asked questions

What does "ERROR: yaml.scanner.ScannerError: while scanning a simple key" mean?
yml file. YAML is extremely sensitive to formatting, and this error typically indicates a structural problem with how your file is written. The "simple key" referenced in the error refers to YAML's internal concept of a key in a key-value pair.
How do I fix "ERROR: yaml.scanner.ScannerError: while scanning a simple key"?
The yaml.scanner.ScannerError in Docker Compose occurs when the YAML parser encounters invalid syntax, usually due to tabs instead of spaces, incorrect indentation, or missing spaces after colons. This is one of the most common Docker Compose errors and is easily fixed by validating your YAML file.
What causes "ERROR: yaml.scanner.ScannerError: while scanning a simple key"?
Tab characters used for indentation instead of spaces (YAML strictly requires spaces) Inconsistent indentation levels (mixing 2-space and 4-space indentation) Missing space after colons in key-value pairs (e.g., "restart:always" instead of "restart: always")
Is the "ERROR: yaml.scanner.ScannerError: while scanning a simple key" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading