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.
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.
The error message includes a line number. Open your docker-compose.yml and go to that line:
yaml: unmarshal errors:
line 15: cannot unmarshal !!str `true` into boolLine 15 has a quoted boolean. Find it and remove the quotes:
# Wrong - line 15
privileged: "true"
# Correct
privileged: trueYAML requires a space after the colon in key-value pairs. This is the most common cause of unmarshal errors:
# 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).
YAML booleans must be unquoted. Quoted booleans become strings and fail to unmarshal:
# WRONG - strings, not booleans
tty: "true"
stdin_open: "false"
privileged: "yes"
# CORRECT - actual booleans
tty: true
stdin_open: false
privileged: trueNote: YAML 1.1 accepted yes, no, on, off as booleans, but Docker Compose now requires true or false.
Port mappings like 8080:80 can be misinterpreted as base-60 numbers. Always quote them:
# 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.
If you see "cannot unmarshal !!str into []string", you're providing a string where an array is expected:
# 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
- startFor complex commands, use the shell form with quotes or the explicit array format.
Docker Compose 2.17+ rejects duplicate merge keys (<<). If using YAML anchors:
# 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: myappAlternatively, merge the anchors into one:
x-base: &base
restart: always
logging:
driver: json-file
services:
app:
<<: *base
image: myappThe compose file version should be a quoted string:
# 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.
Use the built-in config command to validate your compose file:
docker compose configOr use an online YAML validator to check for basic syntax errors before Docker-specific validation.
For more detailed errors, try:
docker compose config --quiet && echo "Valid" || echo "Invalid"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:
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:
deploy:
resources:
limits:
memory: 512M # Works in deploy section
# But in older mem_limit format, use bytes:
mem_limit: 536870912 # 512MB in bytesdockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec