How to fix ERROR: services.web Additional property invalid is not allowed in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 323 views

This error occurs when your docker-compose.yml contains a property name that Docker Compose doesn't recognize. It typically results from typos, using properties from a different Compose file version, or incorrect YAML indentation.

Quick fix

Fixes ERROR: services.web Additional property invalid is not allowed

# Common typos that cause this error:
services:
  web:
    port: "8080:80"      # ❌ Wrong - should be 'ports'
    volume:              # ❌ Wrong - should be 'volumes'
      - ./data:/data
    enviroment:          # ❌ Wrong - should be 'environment'
      - NODE_ENV=prod
    depend_on:           # ❌ Wrong - should be 'depends_on'
      - db

# Correct version:
services:
  web:
    ports:               # ✅ Correct (plural)
      - "8080:80"
    volumes:             # ✅ Correct (plural)
      - ./data:/data
    environment:         # ✅ Correct spelling
      - NODE_ENV=prod
    depends_on:          # ✅ Correct (with 's')
      - db
  1. Check for typos in property names
  2. Verify YAML indentation is correct
  3. Remove or update the version field
  4. Update Docker Compose to the latest version
docker — error
# Common typos that cause this error:
services:
  web:
    port: "8080:80"      # ❌ Wrong - should be 'ports'
    volume:              # ❌ Wrong - should be 'volumes'
      - ./data:/data
    enviroment:          # ❌ Wrong - should be 'environment'
      - NODE_ENV=prod
    depend_on:           # ❌ Wrong - should be 'depends_on'
      - db
# Correct version:
services:
  web:
    ports:               # ✅ Correct (plural)
      - "8080:80"
    volumes:             # ✅ Correct (plural)
      - ./data:/data
    environment:         # ✅ Correct spelling
      - NODE_ENV=prod
    depends_on:          # ✅ Correct (with 's')
      - db
ERROR: services.web Additional property invalid is not allowed

What this error means

The "Additional property is not allowed" error means Docker Compose's YAML schema validator encountered a property name it doesn't recognize in your compose file. Docker Compose validates your configuration against a JSON schema that defines all valid properties for each section (services, networks, volumes, etc.). When Docker Compose parses your file, it checks every key against its expected schema. If it finds a property that isn't defined in the schema for that context, it rejects the entire file with this error. The error message tells you exactly which property is problematic and where it's located (e.g., "services.web" means the "web" service definition). This strict validation helps catch configuration mistakes early, before they cause runtime issues. However, it can be frustrating when valid properties from one Compose version don't work in another, or when a simple typo prevents your stack from starting.

Typical symptoms

  • Running 'docker-compose up' or 'docker compose up' fails immediately with schema validation error
  • Error message shows the exact path and property name that's not allowed
  • The same compose file works on a colleague's machine but not yours
  • Error appears after copying configuration from documentation or tutorials
  • Compose file worked before upgrading Docker or Docker Compose

Common causes

  1. Typo in property name (e.g., 'port' instead of 'ports', 'volume' instead of 'volumes')
  2. Using a property that doesn't exist in your Compose file version
  3. Incorrect YAML indentation placing properties at the wrong level
  4. Using properties only available in newer versions of Docker Compose
  5. Mixing docker-compose v1 syntax with v2/v3 syntax
  6. Using 'docker stack deploy' with properties only supported by 'docker compose'

How to fix "ERROR: services.web Additional property invalid is not allowed"

1Check for typos in property names

The most common cause is a simple typo. Compare your property name against the official schema:

yaml
# Common typos that cause this error:
services:
  web:
    port: "8080:80"      # ❌ Wrong - should be 'ports'
    volume:              # ❌ Wrong - should be 'volumes'
      - ./data:/data
    enviroment:          # ❌ Wrong - should be 'environment'
      - NODE_ENV=prod
    depend_on:           # ❌ Wrong - should be 'depends_on'
      - db

# Correct version:
services:
  web:
    ports:               # ✅ Correct (plural)
      - "8080:80"
    volumes:             # ✅ Correct (plural)
      - ./data:/data
    environment:         # ✅ Correct spelling
      - NODE_ENV=prod
    depends_on:          # ✅ Correct (with 's')
      - db

Run a YAML linter or use your IDE's Docker Compose extension to catch these issues early.

2Verify YAML indentation is correct

Incorrect indentation can make properties appear at the wrong level, causing validation errors:

yaml
# ❌ WRONG - 'ports' is at the wrong indentation level
services:
  web:
    image: nginx
  ports:                 # This is at the services level, not under 'web'
    - "80:80"

# ❌ WRONG - Property appears as a new service
services:
  web:
    image: nginx
    environment:
      - NODE_ENV=prod
  restart: always        # This creates a service called 'restart'

# ✅ CORRECT - All properties properly indented under 'web'
services:
  web:
    image: nginx
    ports:               # Indented under 'web'
      - "80:80"
    environment:
      - NODE_ENV=prod
    restart: always      # Indented under 'web'

Use 2 spaces for indentation (not tabs) and ensure all service properties are at the same level.

3Remove or update the version field

Different Compose file versions support different properties. Remove the version field to use the latest Compose Specification:

yaml
# ❌ Old approach with version field
version: "3.8"
services:
  web:
    image: nginx

# ✅ Modern approach - omit version field
services:
  web:
    image: nginx

When you omit the version field, Docker Compose uses the Compose Specification which supports the widest range of properties. The version field is now considered legacy.

If you must use a version for compatibility, here's what each supports:
- Version 2.x: Full local development features, no Swarm
- Version 3.x: Swarm-compatible but removed some features
- No version (Compose Spec): All features, recommended

4Update Docker Compose to the latest version

Newer Docker Compose versions support more properties. Check and update your version:

bash
# Check current version
docker compose version

# If you have the old docker-compose (with hyphen), upgrade to v2
# On Linux:
sudo apt-get update
sudo apt-get install docker-compose-plugin

# On macOS/Windows:
# Update Docker Desktop to get the latest docker compose

# Verify the update
docker compose version
# Should show: Docker Compose version v2.x.x

Some properties that require newer versions:
- include - requires Compose v2.20+
- configs.content - requires Compose v2.23.1+
- depends_on.required - requires Compose v2.20+
- develop - requires Compose v2.22+

5Check version-specific property availability

Some properties are only available in specific Compose file versions. Here are common ones that cause errors:

yaml
# Properties that need specific versions or contexts:

# ❌ 'deploy' is ignored in docker-compose, only works in Swarm
services:
  web:
    deploy:
      replicas: 3        # Use 'docker stack deploy' for this

# ❌ 'devices' in deploy.resources needs Compose v2.3+
services:
  gpu-app:
    deploy:
      resources:
        reservations:
          devices:       # Requires newer Compose
            - driver: nvidia

# ❌ Extension fields need version 2.1+ or 3.4+
x-logging: &logging      # Needs version that supports extensions
  driver: json-file

# ✅ For maximum compatibility, use the Compose Specification (no version)
services:
  web:
    image: nginx
    # ... modern properties work here

Consult the [Compose Specification](https://docs.docker.com/compose/compose-file/) for the definitive list of valid properties.

6Handle docker stack deploy compatibility

If using docker stack deploy, note it uses a different schema than docker compose:

bash
# These commands use DIFFERENT schemas:
docker compose up        # Compose Specification (more properties)
docker stack deploy      # Legacy version 3.x schema (fewer properties)

Properties that work with docker compose but NOT docker stack deploy:
- build - Swarm requires pre-built images
- depends_on with conditions
- include
- develop
- name at the root level

If you need both, maintain separate files:

bash
# For local development
docker compose -f docker-compose.yml up

# For Swarm deployment (stripped-down version)
docker stack deploy -c docker-stack.yml myapp

Advanced notes

Using extension fields (x-): Extension fields let you define reusable YAML anchors. They must start with x- and are ignored by Compose:

yaml
x-common-env: &common-env
  LOG_LEVEL: info
  TZ: UTC

services:
  web:
    environment:
      <<: *common-env
      PORT: 8080
  worker:
    environment:
      <<: *common-env
      WORKER_COUNT: 4

Note: Extension fields under depends_on don't work in all versions due to strict schema validation.

Validating your Compose file: Use the built-in config command to validate without running:

bash
docker compose config
# or for more verbose output:
docker compose config --quiet && echo "Valid!" || echo "Invalid!"

IDE support: Install the Docker extension for VS Code or the Docker plugin for JetBrains IDEs. These provide real-time validation, autocomplete, and hover documentation for Compose files.

Schema evolution: The Compose Specification is actively developed. Properties like include, develop, and watch are recent additions. If a tutorial uses a property you don't recognize, check when it was added and ensure your Docker Compose version supports it.

Frequently asked questions

What does "ERROR: services.web Additional property invalid is not allowed" mean?
The "Additional property is not allowed" error means Docker Compose's YAML schema validator encountered a property name it doesn't recognize in your compose file. ). When Docker Compose parses your file, it checks every key against its expected schema.
How do I fix "ERROR: services.web Additional property invalid is not allowed"?
This error occurs when your docker-compose.yml contains a property name that Docker Compose doesn't recognize. It typically results from typos, using properties from a different Compose file version, or incorrect YAML indentation.
What causes "ERROR: services.web Additional property invalid is not allowed"?
Typo in property name (e.g., 'port' instead of 'ports', 'volume' instead of 'volumes') Using a property that doesn't exist in your Compose file version Incorrect YAML indentation placing properties at the wrong level
Is the "ERROR: services.web Additional property invalid is not allowed" error serious?
It is a low-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading