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.
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.
The most common cause is a simple typo. Compare your property name against the official schema:
# 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')
- dbRun a YAML linter or use your IDE's Docker Compose extension to catch these issues early.
Incorrect indentation can make properties appear at the wrong level, causing validation errors:
# ❌ 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.
Different Compose file versions support different properties. Remove the version field to use the latest Compose Specification:
# ❌ Old approach with version field
version: "3.8"
services:
web:
image: nginx
# ✅ Modern approach - omit version field
services:
web:
image: nginxWhen 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
Newer Docker Compose versions support more properties. Check and update your version:
# 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.xSome 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+
Some properties are only available in specific Compose file versions. Here are common ones that cause errors:
# 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 hereConsult the [Compose Specification](https://docs.docker.com/compose/compose-file/) for the definitive list of valid properties.
If using docker stack deploy, note it uses a different schema than docker compose:
# 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:
# For local development
docker compose -f docker-compose.yml up
# For Swarm deployment (stripped-down version)
docker stack deploy -c docker-stack.yml myappUsing extension fields (x-): Extension fields let you define reusable YAML anchors. They must start with x- and are ignored by Compose:
x-common-env: &common-env
LOG_LEVEL: info
TZ: UTC
services:
web:
environment:
<<: *common-env
PORT: 8080
worker:
environment:
<<: *common-env
WORKER_COUNT: 4Note: 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:
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.
dockerfile parse error line 5: unknown instruction: RRUN
How to fix 'unknown instruction' Dockerfile parse error in Docker
Error response from daemon: manifest for nginx:nonexistent not found: manifest unknown: manifest unknown
How to fix 'manifest for image:tag not found' in Docker
Error response from daemon: invalid reference format: repository name must be lowercase
How to fix 'repository name must be lowercase' in Docker
Error response from daemon: No such image
How to fix 'No such image' in Docker
Error response from daemon: Container is not running
How to fix 'Container is not running' when using docker exec