What causes "yaml: unmarshal errors: cannot unmarshal"?

Missing whitespace after colons (e.g., 'image:nginx' instead of 'image: nginx') Boolean values wrapped in quotes ('true' instead of true) Single string where an array is expected (command: 'echo hello' instead of command: ['echo', 'hello'])

Is the "yaml: unmarshal errors: cannot unmarshal" error serious?

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

How to fix yaml: unmarshal errors: cannot unmarshal in Docker

Q: What does "yaml: unmarshal errors: cannot unmarshal" mean?

yml file into the expected Go data type. This is a type coercion failure where the YAML contains one data type but Docker Compose expects another. str into int: A string was provided where a number was expected - mapping key already defined: Duplicate YAML merge keys (<<) or duplicate service keys The error message usually includes the line number and the specific type mismatch, helping you locate the problem in your compose file.

DockerBEGINNERLOWUpdated Dec 1, 2025· 342 views

This error occurs when Docker Compose cannot parse your YAML file due to type mismatches, invalid syntax, or formatting issues. The YAML parser expects a specific data type but receives something incompatible.

Quick fix

Fixes yaml: unmarshal errors: cannot unmarshal

yaml: unmarshal errors:
  line 15: cannot unmarshal !!str `true` into bool

Check the line number in the error message
Add spaces after colons
Remove quotes from boolean values
Quote port mappings as strings

docker — error

$yaml: unmarshal errors:
  line 15: cannot unmarshal !!str `true` into bool
yaml: unmarshal errors: cannot unmarshal

What this error means

The "yaml: unmarshal errors: cannot unmarshal" error indicates that Docker Compose's YAML parser failed to convert (unmarshal) a value in your `docker-compose.yml` file into the expected Go data type. This is a type coercion failure where the YAML contains one data type but Docker Compose expects another. Common unmarshal errors include: - **`cannot unmarshal !!str into []string`**: A string was provided where an array was expected - **`cannot unmarshal !!str into bool`**: A quoted boolean like `"true"` was used instead of `true` - **`cannot unmarshal !!str into int`**: A string was provided where a number was expected - **`mapping key already defined`**: Duplicate YAML merge keys (`<<`) or duplicate service keys The error message usually includes the line number and the specific type mismatch, helping you locate the problem in your compose file.

Typical symptoms

Running 'docker-compose up' or 'docker-compose config' fails immediately
Error message shows 'yaml: unmarshal errors' with a line number
The compose file worked before but fails after edits
Error mentions type mismatch like '!!str into []string' or '!!str into bool'
Error reports 'mapping key already defined' for duplicate keys

Common causes

Missing whitespace after colons (e.g., 'image:nginx' instead of 'image: nginx')
Boolean values wrapped in quotes ('true' instead of true)
Single string where an array is expected (command: 'echo hello' instead of command: ['echo', 'hello'])
Duplicate merge keys (<<) in the same mapping (Docker Compose 2.17+)
Duplicate keys at the same YAML level (two 'image:' lines in one service)
Invalid version format ('version: 3' as string instead of 'version: "3"')
Port mappings without quotes ('8080:80' may be parsed as base-60 float)
Memory suffixes in wrong format ('50M' where integer bytes expected)
Tab characters used instead of spaces for indentation

How to fix "yaml: unmarshal errors: cannot unmarshal"

1Check the line number in the error message

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

bash

yaml: unmarshal errors:
  line 15: cannot unmarshal !!str `true` into bool

Line 15 has a quoted boolean. Find it and remove the quotes:

yaml

# Wrong - line 15
privileged: "true"

# Correct
privileged: true

2Add spaces after colons

YAML requires a space after the colon in key-value pairs. This is the most common cause of unmarshal errors:

yaml

# WRONG - no space after colon
image:nginx:latest
ports:8080:80

# CORRECT - space after colon
image: nginx:latest
ports:
  - "8080:80"

Search your file for patterns like :\S (colon followed by non-whitespace).

3Remove quotes from boolean values

YAML booleans must be unquoted. Quoted booleans become strings and fail to unmarshal:

yaml

# WRONG - strings, not booleans
tty: "true"
stdin_open: "false"
privileged: "yes"

# CORRECT - actual booleans
tty: true
stdin_open: false
privileged: true

Note: YAML 1.1 accepted yes, no, on, off as booleans, but Docker Compose now requires true or false.

4Quote port mappings as strings

Port mappings like 8080:80 can be misinterpreted as base-60 numbers. Always quote them:

yaml

# WRONG - may parse incorrectly
ports:
  - 8080:80
  - 3000:3000

# CORRECT - quoted strings
ports:
  - "8080:80"
  - "3000:3000"

This applies to any HOST:CONTAINER format values.

5Fix array syntax for commands and entrypoints

If you see "cannot unmarshal !!str into []string", you're providing a string where an array is expected:

yaml

# WRONG - single string
command: npm run start

# CORRECT - shell form (string)
command: "npm run start"

# CORRECT - exec form (array)
command: ["npm", "run", "start"]

# CORRECT - multi-line array
command:
  - npm
  - run
  - start

For complex commands, use the shell form with quotes or the explicit array format.

6Remove duplicate YAML merge keys

Docker Compose 2.17+ rejects duplicate merge keys (<<). If using YAML anchors:

yaml

# WRONG - duplicate << keys
x-common: &common
  restart: always

x-logging: &logging
  logging:
    driver: json-file

services:
  app:
    <<: *common
    <<: *logging  # Error: mapping key '<<' already defined
    image: myapp

# CORRECT - single merge with multiple anchors
services:
  app:
    <<: [*common, *logging]
    image: myapp

Alternatively, merge the anchors into one:

yaml

x-base: &base
  restart: always
  logging:
    driver: json-file

services:
  app:
    <<: *base
    image: myapp

7Quote the version number

The compose file version should be a quoted string:

yaml

# WRONG - interpreted as float or integer
version: 3
version: 3.8

# CORRECT - quoted string
version: "3"
version: "3.8"

Note: In Docker Compose V2+, the version field is optional and can be omitted entirely.

8Validate your YAML syntax

Use the built-in config command to validate your compose file:

bash

docker compose config

Or use an online YAML validator to check for basic syntax errors before Docker-specific validation.

For more detailed errors, try:

bash

docker compose config --quiet && echo "Valid" || echo "Invalid"

Advanced notes

Understanding YAML type indicators: The !! in error messages like !!str or !!bool are YAML type tags. They tell you what type the parser found:
- !!str - string
- !!int - integer
- !!bool - boolean
- !!map - mapping/dictionary
- !!seq - sequence/array

Version compatibility: Docker Compose V2 (the docker compose command) has stricter YAML parsing than V1 (docker-compose). Files that worked with V1 may fail with V2.

YAML anchors and aliases: When using YAML anchors (&anchor) and aliases (*anchor), ensure the anchor is defined before any alias references it. Anchors must appear earlier in the file than their aliases.

Environment variable handling: Environment variables with special characters should be quoted:

yaml

environment:
  # WRONG - may cause parsing issues
  DATABASE_URL: postgres://user:p@ss@host:5432/db

  # CORRECT - quoted
  DATABASE_URL: "postgres://user:p@ss@host:5432/db"

Memory and resource limits: Memory values must use proper suffixes and may need quotes in certain contexts:

yaml

deploy:
  resources:
    limits:
      memory: 512M  # Works in deploy section

# But in older mem_limit format, use bytes:
mem_limit: 536870912  # 512MB in bytes

Frequently asked questions

What does "yaml: unmarshal errors: cannot unmarshal" mean?: yml file into the expected Go data type. This is a type coercion failure where the YAML contains one data type but Docker Compose expects another. str into int: A string was provided where a number was expected - mapping key already defined: Duplicate YAML merge keys (<<) or duplicate service keys The error message usually includes the line number and the specific type mismatch, helping you locate the problem in your compose file.
How do I fix "yaml: unmarshal errors: cannot unmarshal"?: This error occurs when Docker Compose cannot parse your YAML file due to type mismatches, invalid syntax, or formatting issues. The YAML parser expects a specific data type but receives something incompatible.
What causes "yaml: unmarshal errors: cannot unmarshal"?: Missing whitespace after colons (e.g., 'image:nginx' instead of 'image: nginx') Boolean values wrapped in quotes ('true' instead of true) Single string where an array is expected (command: 'echo hello' instead of command: ['echo', 'hello'])
Is the "yaml: unmarshal errors: cannot unmarshal" error serious?: It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading

📚Docker Official Documentation
📖
Docker Docs: Compose file reference(Official Docs)
📖
Docker Docs: Define services in Compose(Official Docs)
💬
Stack Overflow: Failed to unmarshall yaml(Stack Overflow)
💬
Stack Overflow: cannot unmarshal !!str into config.RawService(Stack Overflow)
🐙
GitHub: Multiple yaml alias not working (mapping key already defined)(GitHub)
🐙
GitHub: mapping key << already defined in version >=2.17.0(GitHub)

How to fix yaml: unmarshal errors: cannot unmarshal in Docker

Quick fix

What this error means

Typical symptoms

Common causes

How to fix "yaml: unmarshal errors: cannot unmarshal"

Advanced notes

Frequently asked questions

Related errors

Official resources & further reading