Why does my docker-compose.yml fail with a cryptic YAML error even though it looks fine to me?

Question

I keep hitting yaml: line X: mapping values are not allowed in this context type errors in my docker-compose.yml on my Droplet. The file looks correctly indented to my eye but something is clearly wrong. Is there a good way to actually understand YAML syntax rules rather than just guessing and reformatting until it works? I feel like I am fighting whitespace more than writing config.

Bobby · Answer

Hi there, YAML errors like this are almost always whitespace-related and invisible to the eye because tabs and spaces look identical, and inconsistent indentation between sibling keys is the most common culprit. Check for tabs mixed with spaces first, this is the single most common cause of that exact error: cat -A docker-compose.yml | grep -P '	' If that returns any lines, you have a tab where YAML expects spaces. YAML forbids tabs for indentation entirely. Validate the file properly rather than guessing: python3 -c "import yaml, sys; yaml.safe_load(open('docker-compose.yml'))" This gives you a much clearer error than Docker Compose’s own parser, including the exact line and column. Common causes of “mapping values are not allowed in this context” specifically: A colon inside a string value that is not quoted, YAML tries to interpret it as a new key: # Wrong environment: DATABASE_URL: postgres://user:pass@host:5432/db # Right environment: DATABASE_URL: "postgres://user:pass@host:5432/db" Inconsistent indentation between sibling list items or keys at the same level, even one space off breaks the structure: services: app: image: myapp ports: # one extra space here breaks everything below it - "3000:3000" For actually validating Compose files specifically rather than generic YAML: docker compose config This parses your file the same way Docker Compose does internally and prints the fully resolved config, or the exact error with line number if something is wrong. Run this before docker compose up as a habit and you catch these before they cost you a deploy. If you want to understand what is actually happening under the hood when Compose brings up a container, this Docker internals visualizer walks through the CLI, daemon, and runtime layer by layer, useful context once your YAML is actually valid and you are debugging why the container itself is not behaving as expected.

Become a contributor for community

DigitalOcean Documentation

Resources for startups and AI-native businesses

The developer cloud

Start building today

Report this

Why does my docker-compose.yml fail with a cryptic YAML error even though it looks fine to me?

Related questions

How to tell if Docker Compose is recreating containers for no reason, and whether 5.5 actually fixes it

How to tell if your reverse proxy is buffering your token stream (and why I had to rent a Droplet to find out)

Getting "unauthorized: authentication required" when pushing a docker image

Docker Networking Explained: How Containers Talk to Each Other

What is the best way to learn Docker networking before deploying multi-container apps on a Droplet?

Where do I start with DevOps as a beginner on DigitalOcean?

How do I test my app's error handling before deploying, without breaking my real Droplet?

Where do I start with Docker as a complete beginner?

App Platform Docker builds broken due to no BuildKit

Best way to deploy a small Docker app on DigitalOcean without overengineering?

Registry showing wrong limit

Droplet: Docker => laravel (mysql) + astro app [unusable]

Report this

Why does my docker-compose.yml fail with a cryptic YAML error even though it looks fine to me?

Related questions

How to tell if Docker Compose is recreating containers for no reason, and whether 5.5 actually fixes it

How to tell if your reverse proxy is buffering your token stream (and why I had to rent a Droplet to find out)

Getting "unauthorized: authentication required" when pushing a docker image

Docker Networking Explained: How Containers Talk to Each Other

What is the best way to learn Docker networking before deploying multi-container apps on a Droplet?

Where do I start with DevOps as a beginner on DigitalOcean?

How do I test my app's error handling before deploying, without breaking my real Droplet?

Where do I start with Docker as a complete beginner?

App Platform Docker builds broken due to no BuildKit

Best way to deploy a small Docker app on DigitalOcean without overengineering?

Registry showing wrong limit

Droplet: Docker => laravel (mysql) + astro app [unusable]