Docker Compose "Additional property X is not allowed" in CI

By Kaveh Alemi·Latchkey

Compose validated your file against its schema and found a key it does not recognize at that position. Usually a typo (enviroment), a wrong nesting level, or a key that belongs elsewhere.

What this error means

A docker compose up/config fails with services.<name> Additional property <key> is not allowed. The file parses as YAML but violates the Compose schema at the named key.

docker compose output

services.web Additional property buld is not allowed
# "buld" is a typo for "build"; the schema has no "buld" key

Diagnose it: read the resolved config, not the file you wrote

Compose merges override files, interpolates variables, and applies defaults before it does anything. Most Compose failures in CI are visible in the resolved configuration and invisible in the source file, because the value you are debugging came from an unset variable that quietly became an empty string.

Terminal

# the fully merged, interpolated configuration Compose will actually run
docker compose config

# fail loudly on unset variables instead of silently interpolating empty
docker compose --env-file .env config --quiet || echo "invalid"

# which override files were picked up
docker compose config --services

Common causes

A misspelled key

Typos like buld, enviroment, volums, or command_line are not in the schema, so Compose reports them as disallowed additional properties.

A key at the wrong nesting level

A valid key placed under the wrong parent (e.g. image under build: instead of under the service) is "additional" where it sits, even though it is valid elsewhere.

A key from a different Compose spec version

A property only valid in another schema version, or removed/renamed, fails validation against the version in use.

How to fix it

Fix the key name and indentation

Correct the typo or move the key to the right level.

docker-compose.yml

services:
  web:
    build: ./web        # not "buld"
    environment:        # not "enviroment"
      - NODE_ENV=production

Validate against the schema

Render the resolved config so the exact offending key is reported.

Terminal

docker compose config

Bind mounts behave differently on a runner

A relative bind source is resolved against the compose file location, not the working directory of the shell that invoked it.
The host path must exist before up. Compose creates missing directories for named volumes but not for bind mounts, and the failure surfaces as a mount error rather than a missing-path error.
On a CI runner the workspace path differs from your machine, so any absolute host path in a compose file is a portability bug waiting for its first CI run.
Prefer named volumes for anything that does not genuinely need to be read from the host. They remove the whole class of problem.

How to prevent it

Run docker compose config in CI before bringing services up.
Use an editor with the Compose JSON schema for inline key validation.
Keep indentation consistent so keys attach to the intended parent.

Frequently asked questions

What causes Docker Compose "Additional property X is not allowed" in CI?

There are 3 common causes: a misspelled key, a key at the wrong nesting level, and a key from a different compose spec version. Typos like buld, enviroment, volums, or command_line are not in the schema, so Compose reports them as disallowed additional properties.

How do I fix Docker Compose "Additional property X is not allowed" in CI?

There are 2 fixes depending on which cause you have: fix the key name and indentation and validate against the schema. Work through them in order, since the first is the most common.

What does Docker Compose "Additional property X is not allowed" in CI actually mean?

A docker compose up/config fails with services.<name> Additional property <key> is not allowed.

How do I stop Docker Compose "Additional property X is not allowed" in CI happening again?

Run docker compose config in CI before bringing services up. The prevention section lists 3 changes that keep it from recurring.