How to fix services.myservice Additional property X is not allowed in Docker

DockerBEGINNERLOWUpdated Dec 6, 2025· 322 views

The 'Additional property is not allowed' error in Docker Compose occurs when your docker-compose.yml file contains an unrecognized property name. This is usually caused by typos, incorrect indentation, missing the 'services' key, or using features not supported by your Compose version.

Quick fix

Fixes services.myservice Additional property X is not allowed

services.web Additional property enviroment is not allowed
  1. Check the error message for the exact property name
  2. Ensure services are under the 'services:' key
  3. Fix YAML indentation issues
  4. Validate your Compose file
docker — error
services.web Additional property enviroment is not allowed
services.myservice Additional property X is not allowed

What this error means

The "Additional property X is not allowed" error is Docker Compose's way of telling you that it found a property in your YAML file that doesn't belong where you placed it. Docker Compose validates your file against a schema, and this error triggers when: 1. **A property is misplaced**: You've put a valid property in the wrong location (e.g., `deploy` at the root level instead of under a service) 2. **A property is misspelled**: Common typos like `enviroment` instead of `environment`, or `service` instead of `services` 3. **Indentation is wrong**: YAML is whitespace-sensitive, and incorrect indentation can make a property appear at the wrong level 4. **Missing parent key**: Services defined without a `services:` parent key in Compose file version 2+ The error message format is helpful: `services.myservice Additional property X is not allowed` tells you exactly which property (`X`) is problematic and where it was found (`services.myservice`). Docker Compose has different file format versions (2.x, 3.x, and the modern Compose Specification), each with its own valid properties. Using a feature from a newer version with an older docker-compose tool will also trigger this error.

Typical symptoms

  • Docker Compose fails immediately with 'Additional property X is not allowed'
  • The error message shows the exact property name and location (e.g., 'services.web Additional property enviroment is not allowed')
  • Running `docker compose config` or `docker-compose config` shows the validation error
  • The same docker-compose.yml works on another machine but fails on yours
  • Copy-pasted configuration from a tutorial doesn't work
  • CI/CD pipeline fails at docker-compose validation step

Common causes

  1. Typo in a property name (e.g., 'enviroment' instead of 'environment', 'sevices' instead of 'services')
  2. Missing 'services:' key at the top level (required for Compose file version 2+)
  3. Incorrect YAML indentation placing a property at the wrong nesting level
  4. Using a property not supported by your Docker Compose version (e.g., 'include' requires Compose 2.20+)
  5. Wrong top-level key (e.g., 'service:' instead of 'services:')
  6. Property placed under wrong parent (e.g., 'volumes' under 'build' instead of under the service)
  7. Using tabs instead of spaces for indentation in YAML

How to fix "services.myservice Additional property X is not allowed"

1Check the error message for the exact property name

The error message tells you exactly which property is problematic. Read it carefully:

bash
services.web Additional property enviroment is not allowed

In this example:
- Location: services.web - the problem is in the "web" service
- Property: enviroment - this is the unrecognized property (note the typo!)

Common typos to look for:
| Wrong | Correct |
|-------|---------|
| enviroment | environment |
| sevices | services |
| service | services |
| env_files | env_file |
| port | ports |
| volume | volumes |
| depens_on | depends_on |
| bulid | build |

2Ensure services are under the 'services:' key

In Compose file version 2 and later, all service definitions must be nested under a services: key. This is the most common cause of this error for beginners.

Wrong - services at root level:

yaml
version: "3"
web:
  image: nginx
  ports:
    - "80:80"

Correct - services under 'services:' key:

yaml
version: "3"
services:
  web:
    image: nginx
    ports:
      - "80:80"

If you see an error like (root) Additional property web is not allowed, this is almost certainly the cause.

3Fix YAML indentation issues

YAML requires consistent indentation with spaces (not tabs). Incorrect indentation can make properties appear at the wrong level.

Wrong - deploy appears as a separate service:

yaml
services:
  web:
    image: nginx
  deploy:              # Wrong! This looks like a service named "deploy"
    replicas: 3

Correct - deploy is a property of web:

yaml
services:
  web:
    image: nginx
    deploy:            # Correct! Indented under web
      replicas: 3

Use a YAML validator or your editor's YAML support to check indentation. Most editors can visualize indentation levels.

To check for tabs vs spaces:

bash
# Show tabs as ^I
cat -A docker-compose.yml

# Or use grep to find tabs
grep -P '\t' docker-compose.yml

If you find tabs, replace them with spaces (typically 2 spaces per level):

bash
# Replace tabs with 2 spaces
sed -i 's/\t/  /g' docker-compose.yml
4Validate your Compose file

Use Docker Compose's built-in validation to check your file:

bash
# Using Docker Compose V2 (recommended)
docker compose config

# Using legacy docker-compose
docker-compose config

This command parses and validates your file, showing exactly where problems occur. If the file is valid, it outputs the processed configuration.

You can also use online validators:
- [Docker Compose Validator](https://yamlchecker.com/) - General YAML validation
- Your IDE's built-in YAML/Docker Compose support

For a quick syntax check without running Docker:

bash
# Check YAML syntax with Python
python3 -c "import yaml; yaml.safe_load(open('docker-compose.yml'))"
5Check your Docker Compose version for feature support

Some properties are only available in newer Docker Compose versions. Check your version:

bash
docker compose version
# or
docker-compose --version

Common properties and their minimum version requirements:

| Property | Minimum Version |
|----------|-----------------|
| include | Docker Compose 2.20.0 |
| configs.*.content | Docker Compose 2.23.0 |
| deploy.replicas | Compose file version 3.0+ |
| healthcheck | Compose file version 2.1+ |
| platform | Docker Compose 2.4.0 |

If you're using a feature not supported by your version, either:
1. Upgrade Docker Compose: sudo apt-get update && sudo apt-get install docker-compose-plugin
2. Remove the unsupported property from your file
3. Use an alternative approach compatible with your version

6Review valid top-level keys

Docker Compose only allows specific top-level keys. Using anything else triggers this error.

Valid top-level keys:

yaml
version: "3.8"          # Optional in Compose V2
name: my-project        # Project name (optional)
services:               # Service definitions (required)
networks:               # Network definitions (optional)
volumes:                # Volume definitions (optional)
configs:                # Config definitions (optional)
secrets:                # Secret definitions (optional)
x-*:                    # Extension fields (optional)
include:                # Include other files (Compose 2.20+)

Invalid example:

yaml
version: "3"
myservice:              # Wrong! Should be under 'services:'
  image: nginx

The error (root) Additional property myservice is not allowed means you're defining something at the root level that isn't one of the valid top-level keys.

7Fix property placement within services

Each service has a specific set of allowed properties. Common misplacements include:

Wrong - environment under build:

yaml
services:
  web:
    build:
      context: .
      environment:     # Wrong! environment goes under service, not build
        - NODE_ENV=prod

Correct - environment under service:

yaml
services:
  web:
    build:
      context: .
    environment:       # Correct! At service level
      - NODE_ENV=prod

Common service-level properties:
- image, build, command, entrypoint
- environment, env_file
- ports, expose
- volumes, networks
- depends_on, links
- deploy, healthcheck
- restart, container_name

When in doubt, consult the [Compose Specification](https://docs.docker.com/compose/compose-file/) for the complete list.

Advanced notes

### Understanding Compose Schema Validation

Docker Compose validates your file against a JSON schema. The schema defines:
- Which properties are valid at each level
- Required vs optional properties
- Property types (string, array, object)
- Allowed values for certain properties

Starting with Compose V2, validation uses the Compose Specification schema regardless of the version: field. The version field is now obsolete and only informative.

### Common "Additional property" Error Patterns

Pattern 1: `(root) Additional property X is not allowed`
- X is at the top level but isn't a valid top-level key
- Usually means services aren't under services:

Pattern 2: `services.myservice Additional property X is not allowed`
- X is under a service but isn't a valid service property
- Check for typos or wrong nesting level

Pattern 3: `services.myservice.build Additional property X is not allowed`
- X is under the build section but isn't valid there
- build: has limited properties: context, dockerfile, args, etc.

### IDE Support for Validation

Modern IDEs can validate docker-compose.yml files in real-time:

VS Code:
- Install the "Docker" extension
- Install the "YAML" extension by Red Hat
- Add to settings.json:

json
{
  "yaml.schemas": {
    "https://raw.githubusercontent.com/compose-spec/compose-spec/master/schema/compose-spec.json": ["docker-compose*.yml", "compose*.yml"]
  }
}

JetBrains IDEs (IntelliJ, PyCharm, WebStorm):
- Docker support is built-in
- Enable the Docker plugin for enhanced validation

### Extension Fields (x-*)

If you need custom properties for templating or documentation, use extension fields that start with x-:

yaml
x-common-variables: &common-vars
  MYSQL_USER: app
  MYSQL_PASSWORD: secret

services:
  web:
    environment:
      <<: *common-vars
      APP_ENV: production

Extension fields are ignored by Docker Compose and won't trigger validation errors.

### Differences Between Compose Versions

The allowed properties vary between Compose file versions:

| Feature | Version 2.x | Version 3.x |
|---------|-------------|-------------|
| mem_limit | Yes | No (use deploy.resources) |
| cpu_shares | Yes | No (use deploy.resources) |
| deploy | Limited | Full support |
| depends_on.condition | Yes | No (Swarm ignores) |

If you're seeing errors after copying from an old tutorial, check if the properties used are compatible with your Compose file version.

Frequently asked questions

What does "services.myservice Additional property X is not allowed" mean?
The "Additional property X is not allowed" error is Docker Compose's way of telling you that it found a property in your YAML file that doesn't belong where you placed it. Docker Compose validates your file against a schema, and this error triggers when: 1. , deploy at the root level instead of under a service) 2.
How do I fix "services.myservice Additional property X is not allowed"?
The 'Additional property is not allowed' error in Docker Compose occurs when your docker-compose.yml file contains an unrecognized property name. This is usually caused by typos, incorrect indentation, missing the 'services' key, or using features not supported by your Compose version.
What causes "services.myservice Additional property X is not allowed"?
Typo in a property name (e.g., 'enviroment' instead of 'environment', 'sevices' instead of 'services') Missing 'services:' key at the top level (required for Compose file version 2+) Incorrect YAML indentation placing a property at the wrong nesting level
Is the "services.myservice Additional property X 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