Unity-Technologies/ml-agents · error · ValueError

num_areas must be set to a positive number >= 1.

Error message

num_areas must be set to a positive number >= 1.

What it means

A validator on the num_areas attribute of the environment settings rejects the configured value: num_areas must be an integer >= 1 because it tells the trainer how many Area agents to expect in the environment. It fires when the YAML config or CLI default supplies zero, a negative number, or a non-positive value, making per-area worker/scaling logic impossible.

Source

Thrown at ml-agents/mlagents/trainers/settings.py:836

    num_envs: int = attr.ib(default=parser.get_default("num_envs"))
    num_areas: int = attr.ib(default=parser.get_default("num_areas"))
    timeout_wait: int = attr.ib(default=parser.get_default("timeout_wait"))
    seed: int = parser.get_default("seed")
    max_lifetime_restarts: int = parser.get_default("max_lifetime_restarts")
    restarts_rate_limit_n: int = parser.get_default("restarts_rate_limit_n")
    restarts_rate_limit_period_s: int = parser.get_default(
        "restarts_rate_limit_period_s"
    )

    @num_envs.validator
    def validate_num_envs(self, attribute, value):
        if value > 1 and self.env_path is None:
            raise ValueError("num_envs must be 1 if env_path is not set.")

    @num_areas.validator
    def validate_num_area(self, attribute, value):
        if value <= 0:
            raise ValueError("num_areas must be set to a positive number >= 1.")


@attr.s(auto_attribs=True)
class EngineSettings:
    width: int = parser.get_default("width")
    height: int = parser.get_default("height")
    quality_level: int = parser.get_default("quality_level")
    time_scale: float = parser.get_default("time_scale")
    target_frame_rate: int = parser.get_default("target_frame_rate")
    capture_frame_rate: int = parser.get_default("capture_frame_rate")
    no_graphics: bool = parser.get_default("no_graphics")
    no_graphics_monitor: bool = parser.get_default("no_graphics_monitor")


@attr.s(auto_attribs=True)
class TorchSettings:
    device: Optional[str] = parser.get_default("device")

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Set num_areas in the environment_settings section of your training config YAML to the actual number of areas in your Unity scene (>= 1)
2. If your environment has a single area, explicitly set num_areas: 1
3. Ensure the value is an integer, not a float or string

When it happens

Trigger: Thrown at ml-agents/mlagents/trainers/settings.py:836 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of Unity-Technologies/ml-agents@3ecb446f75 (2026-09-02). Data as JSON: /api/errors/9743e177f2b92eab. Report an issue: GitHub.