Docker Compose YAML Indentation Error: Solving 'Additional Property Replicas is Not Allowed'

Problem Background and Error Analysis

When using Docker Compose for container orchestration, the indentation and structure of YAML files are crucial. Many developers encounter errors like "Additional property replicas is not allowed" when running docker-compose up or docker stack deploy commands. This error typically stems from structural issues in the YAML file, particularly the incorrect placement of the deploy section.

Core Importance of YAML Indentation Rules

YAML is a language extremely sensitive to indentation. In Docker Compose configurations, incorrect indentation causes the parser to misinterpret the hierarchical relationships between configuration items. In the original problem, the deploy section was erroneously placed at the same level as services, rather than as a child property of the web service.

Incorrect configuration example:

version: "3"
   services:
     web:
       image: tuhina/friendlyhello:2.0
     deploy:
       replicas: 5
       resources:
         limits:
           cpus: "0.1"
           memory: 50M
      restart_policy:
        condition: on-failure
      ports:
        - "80:80"
      networks:
        - webnet
    networks:
      webnet:

In this configuration, deploy is incorrectly treated as an independent service rather than deployment configuration for the web service.

Implementation of Correct Configuration

The correct configuration should place the deploy section as a direct child property of the web service:

version: "3"

services:
  web:
    image: tuhina/friendlyhello:2.0
    deploy:
      replicas: 5
      resources:
        limits:
          cpus: "0.1"
          memory: '50M'
      restart_policy:
        condition: on-failure
    ports:
      - "80:80"
    networks:
      - webnet

networks:
  webnet:

In this corrected configuration:

• The deploy section is properly nested under the web service
• The replicas property now resides at the correct hierarchy level, no longer triggering the "additional property" error
• All configuration items maintain proper indentation levels

Version Compatibility Considerations

Based on user feedback from reference materials, version differences in Docker Compose can also cause configuration parsing issues. Newer Docker Compose versions (v2.x) use the docker compose command, while older versions (v1.x) use docker-compose. In v2 versions, the top-level version declaration is no longer required, but it's recommended to retain it for backward compatibility.

Check the currently used Docker Compose version:

docker-compose --version
# or for v2
docker compose version

Debugging and Verification Recommendations

When encountering YAML configuration errors, follow these debugging steps:

1. Use YAML validation tools to check file syntax
2. Gradually comment out configuration sections to locate the problem
3. Refer to the official Docker Compose specification documentation
4. Ensure all configuration items are at the correct indentation levels

Room for Improvement in Error Messaging

As noted in user feedback from reference materials, Docker error messages can sometimes be too vague, causing frustration for beginners. While accurate, error messages like "Additional property X is not allowed" lack specific guidance. We recommend the Docker team provide more detailed error localization and repair suggestions in future versions.

Best Practices Summary

To avoid similar configuration errors, developers should:

• Always use consistent indentation (recommended: 2 spaces)
• Enable YAML syntax highlighting and indentation guides in editors
• Regularly consult the official Docker Compose specification documentation
• Establish unified configuration writing standards within teams
• Use version control to track configuration changes

By following these best practices, the frequency of Docker Compose configuration errors can be significantly reduced, improving development efficiency.