Unity-Technologies/ml-agents · error · ValueError

num_envs must be 1 if env_path is not set.

Error message

num_envs must be 1 if env_path is not set.

What it means

RunOptions.num_envs controls concurrent Unity environment instances; this only makes sense when an env_path points to a build. If env_path is None (training in the editor) and num_envs > 1, an attrs validator raises ValueError.

Source

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

@attr.s(auto_attribs=True)
class EnvironmentSettings:
    env_path: Optional[str] = parser.get_default("env_path")
    env_args: Optional[List[str]] = parser.get_default("env_args")
    base_port: int = parser.get_default("base_port")
    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")

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Set num_envs: 1 in the config when training in the Unity editor (no env_path).
2. Alternatively, provide env_path pointing to a built environment executable and keep num_envs > 1.
3. Use --num-envs CLI flag consistently with whether --env is supplied.

Example fix

# before (editor training)
env: null
num_envs: 8
# after
env: null
num_envs: 1

if opts.env_path is None and opts.num_envs > 1:
    raise ValueError('num_envs must be 1 when training without an env build')

def valid_num_envs(env_path, num_envs):
    return env_path is not None or num_envs == 1

try:
    run_training(run_options)
except ValueError as e:
    if 'num_envs must be 1' in str(e):
        run_options.num_envs = 1
        run_training(run_options)

When it happens

Trigger: Running mlagents-learn with an editor-based (no --env) training run while num_envs is set to a value greater than 1 in the config.

Common situations: Reusing a config written for executable-based training inside Unity editor training; copying example configs that set num_envs: 8 without an env build path.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Config file could not be found at {abs_path}.
• There was an error decoding Config file from {config_path}.
• Error parsing yaml file. Please check for formatting errors.
• Threshold for next lesson cannot be negative when the measur
• A non-terminal lesson does not have a completion_criteria fo

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