Docker Compose Validator

Overview

Checks a docker-compose.yml or compose.yaml file for the mistakes that stop docker compose up: services with no image or build, invalid or clashing port mappings, depends_on targets that do not exist, undefined volumes and networks, bad environment formats, invalid restart policies and the obsolete version key. Each problem is listed with its line number.

How It Works

Paste your Compose file into the box. The YAML is parsed with the yaml library, so syntax errors and duplicate keys are reported with a line number, and the structure is then checked against the Compose Specification. Results are grouped as errors, warnings and notes, and the filter buttons narrow the list. Fix the first error and the list updates immediately. The report can be downloaded to attach to a review or a ticket.

Step-by-Step Usage Guide

1. Paste the contents of your docker-compose.yml or compose.yaml into the box.
2. Start with the Errors filter and fix each one, using the line number and path shown.
3. Review the warnings, especially unknown keys, unused volumes and missing healthchecks.
4. Run docker compose config in your project folder as a last check before deploying.

Technical Specifications & Standards

Errors are problems Compose would reject or that cannot work: a service with neither image nor build, a port such as 99999:80, a host port published by two services, a depends_on entry that names a missing service or forms a cycle, a named volume or network that is not declared at the top level, or a restart value that is not no, always, on-failure[:N] or unless-stopped. Warnings cover things that are legal but suspicious, such as an unknown service key (with a hint for typos like port or depend_on), a service waiting for service_healthy on a target that has no healthcheck, a top-level volume or network nothing uses, and the top-level version key, which current Docker Compose ignores and warns about. Port strings are parsed as [HOST_IP:][HOST:]CONTAINER[/protocol], including ranges and bracketed IPv6 addresses, and two mappings clash only when the protocol matches, the host ranges overlap and the bound addresses overlap, so 127.0.0.1:9000 and 127.0.0.2:9000 are fine while 9000 and 127.0.0.1:9000 are not. In short volume syntax a source that starts with ., / or ~ or contains a path separator is a bind mount, and anything else is a named volume that must be declared. Anchors, merge keys and x- extension fields are supported. This is a static lint: it does not read env_file paths, build contexts or included files, does not expand ${VARIABLE} values, and does not pull images. Run docker compose config as a final authoritative check.

Targeted Use Cases

• Catching a host port conflict between two services before the second container fails to start.
• Finding the typo in depends_on or networks that produces a confusing startup error.
• Reviewing a Compose file written by someone else before running it.
• Cleaning up an old file by spotting the obsolete version key and unused volumes.

Notes & Gotchas

• Quote port mappings such as "8080:80" so YAML tools cannot read them as numbers.
• Pin image tags or digests instead of relying on latest, so deployments are repeatable.
• Give any service that others wait on with service_healthy a real healthcheck.
• Keep secrets out of the Compose file by using env_file, interpolation or Compose secrets.

Frequently Asked Questions