Why compose files break in quiet, confusing ways
YAML's whitespace-sensitive syntax means a docker-compose.yml file can look perfectly readable and still fail — or worse, silently misconfigure a service — because of a small structural mistake. Unlike a programming language with a compiler that throws a clear error, YAML parsers can sometimes accept malformed structure and just interpret it differently than you intended, which is far more dangerous than an outright crash.
The mistakes that show up most often
Missing image or build. Every service needs one of the two so Docker knows what to actually run. It's an easy thing to forget when copy-pasting a service block and stripping out the image line to "fill in later."
Malformed port mappings. The standard format is "HOST:CONTAINER", but it's common to accidentally reverse the order, use a non-numeric value, or leave only one side. A port mapping like "abc:80" won't fail loudly — it fails at container start time, often with a less-than-obvious error.
Duplicate service names. When editing a large compose file, it's easy to copy a service block, rename most of it, and forget to change the top-level key — silently overwriting the first definition rather than adding a second service.
Mixed tabs and spaces. YAML technically forbids tabs for indentation, but many editors will insert them anyway depending on settings, producing files that look fine visually but parse incorrectly.
What a scoped structural validator catches — and what it doesn't
A lightweight, purpose-built validator that understands typical compose structure (services, image, ports, volumes, environment, depends_on, networks) can catch the mistakes above quickly, with a line number, before you ever run docker compose up. What it deliberately does not attempt is full YAML spec compliance — anchors and aliases, complex merge keys, and exotic flow-style folding are outside the scope of a tool built around the common 90% of real-world compose files. For a final, guaranteed-correct check, always run docker compose config as well, which uses Docker's own official parser.
A quick pre-deploy checklist
- Every service has either
image:orbuild:. - Every port mapping follows
"HOST:CONTAINER"with both sides numeric. - No two services share the same top-level name.
- Indentation is consistent — spaces only, and aligned with sibling entries.
- Run
docker compose configas a final sanity check against the real parser before deploying.
Catching these structural issues in seconds, before a deploy, beats debugging a half-started stack after the fact.
Frequently Asked Questions
No — it's a fast, offline pre-check for the most common structural mistakes. It uses a minimal indentation-based parser scoped to typical compose files, not a full YAML spec parser. Always run docker compose config as your final, authoritative check before deploying.
Yes — Docker Compose YAML Validator checks your pasted compose file for missing image/build keys, malformed ports and volumes, duplicate services, and indentation issues, all in your browser. It's a one-time $5.49 purchase — no subscription, no account required.
No, and this is stated explicitly in the tool. It validates common docker-compose structure — services, image, build, ports, volumes, environment, depends_on, networks — but exotic YAML features like anchors, aliases, and complex merge keys are out of scope.
Yes — it checks that both sides of a HOST:CONTAINER port mapping look like valid port numbers and flags mismatches with the specific line number.
No. Parsing and validation happen entirely in JavaScript inside your browser. Nothing you paste is sent to a server.