🚨 Docker Error Guide: 'Additional property is not allowed' — Invalid Compose Key

Overview

Compose validates your file against its schema and rejects an unknown key:

services.web Additional property enviroment is not allowed

Compose only accepts a defined set of properties under each service. When it finds a key it does not recognize — a misspelling like enviroment, a misindented option that landed at the wrong level, or a genuinely unsupported field — schema validation fails and the whole project is rejected. The message tells you exactly where: the path (services.web) and the offending property name.

Symptoms

• docker compose config and docker compose up fail with Additional property <key> is not allowed.
• The named key looks almost right — enviroment, command_line, port, volume (singular) instead of volumes.
• A valid option appears under the wrong parent because indentation nested it incorrectly.
• The file worked on an older Compose that tolerated an extra key, and breaks after an upgrade.
• A build option was placed directly under the service instead of under build:.

Common Root Causes

• Misspelled key. enviroment for environment, containers_name for container_name, image_name for image.
• Wrong indentation. A key like context: or dockerfile: sits directly under the service instead of nested under build:.
• Singular vs plural mistakes. port/volume/network instead of ports/volumes/networks.
• Unsupported or removed field for the schema Compose is validating against.
• Key placed at the wrong scope — a top-level option written inside a service, or a service option written at the top level.

Diagnostic Workflow

Let Compose validate and point at the exact path and property:

docker compose config

Read the error path carefully: services.web <key> means the bad key is directly under the web service. Compare against a known-good structure. Here is a file with a misspelled key and a misindented build option:

services:
  web:
    image: registry.example.com/myapp:1.4.2
    enviroment:            # typo -> not a valid property
      - LOG_LEVEL=info
    dockerfile: Dockerfile # misindented: belongs under build:

The corrected version fixes the spelling and nests dockerfile under build::

services:
  web:
    build:
      context: .
      dockerfile: Dockerfile
    image: registry.example.com/myapp:1.4.2
    environment:
      - LOG_LEVEL=info

Re-validate, then start:

docker compose config
docker compose up -d

Example Root Cause Analysis

A team added health-check tuning to a service and pasted the options from a snippet. The result was:

services:
  web:
    image: registry.example.com/myapp:1.4.2
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
    interval: 30s          # wrong scope
    retries: 3             # wrong scope

Compose failed with services.web Additional property interval is not allowed. The interval and retries options are valid — but only inside the healthcheck: block, not directly under the service. Because they were indented at the service level, Compose saw two unknown service properties.

docker compose config reported the exact path (services.web interval), which made the scope error obvious. The fix was to move interval and retries under healthcheck:. After re-running docker compose config, the file validated and the stack came up. The takeaway: Additional property is not allowed is frequently not a typo at all but a valid key living at the wrong indentation level.

Prevention Best Practices

• Validate with docker compose config before every deploy — it catches unknown keys without starting containers.
• Lint YAML for indentation. Most of these errors are scope/indent mistakes a linter flags instantly. Use the Dockerfile & Compose validator.
• Watch singular vs plural: ports, volumes, networks, environment are all plural/collective.
• Keep nested options nested. context/dockerfile under build:; interval/retries/timeout under healthcheck:.
• Use editor schema support (Compose JSON schema in your IDE) so unknown keys are underlined as you type.

Quick Command Reference

# Validate the file and get the exact bad-key path
docker compose config

# Common valid keys to sanity-check spelling/scope:
#   image, build, ports, volumes, environment, depends_on,
#   networks, healthcheck, container_name, restart

# Start after validation passes
docker compose up -d

Conclusion

services.<svc> Additional property <key> is not allowed means Compose found a key its schema does not accept — a typo, a singular/plural slip, or (very often) a valid option at the wrong indentation level. Let docker compose config pinpoint the path, fix the spelling or nesting, and re-validate. Adding that validation step to CI turns schema mistakes into fast, obvious failures before they ever reach a running host.