Compose "additional property ... is not allowed" schema error in CI

By Daniel Zoghalchali·Latchkey

Compose validates the file against its schema before doing anything. "additional property <key> is not allowed" means a key is misspelled or placed at the wrong level, so the schema rejects it.

What this error means

A compose command fails with "validating docker-compose.yml: services.web additional property buld is not allowed" or a similar unexpected-key message.

validating docker-compose.yml: services.web additional property buld is not allowed

Common causes

A misspelled key

A typo like buld instead of build, or enviroment instead of environment, is not a known schema property.

A key at the wrong nesting level

A valid key placed under the wrong parent (for example a build option directly under the service) is rejected by the schema.

How to fix it

Correct the key name and placement

1. Read the path in the message (e.g. services.web) and the offending property.
2. Fix the spelling or move the key under the correct parent.
3. Re-validate with docker compose config.

services:
  web:
    build: ./web
    environment:
      - NODE_ENV=test

Validate the file in CI before using it

Run config validation as an early step so schema errors fail fast with a clear path.

docker compose config -q

How to prevent it

• Validate compose files with docker compose config in CI.
• Use editor schema support to catch unknown keys.
• Mind nesting levels for build and deploy options.

Frequently asked questions

Related guides

References

• Docker documentation
• Docker build cache
• GitHub Actions documentation