{"record":{"id":"4bdda3811dbaf1fd","repo":"Unity-Technologies/ml-agents","slug":"num-envs-must-be-1-if-env-path-is-not-set","errorCode":null,"errorMessage":"num_envs must be 1 if env_path is not set.","messagePattern":"num_envs must be 1 if env_path is not set\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"ml-agents/mlagents/trainers/settings.py","lineNumber":831,"sourceCode":"@attr.s(auto_attribs=True)\nclass EnvironmentSettings:\n    env_path: Optional[str] = parser.get_default(\"env_path\")\n    env_args: Optional[List[str]] = parser.get_default(\"env_args\")\n    base_port: int = parser.get_default(\"base_port\")\n    num_envs: int = attr.ib(default=parser.get_default(\"num_envs\"))\n    num_areas: int = attr.ib(default=parser.get_default(\"num_areas\"))\n    timeout_wait: int = attr.ib(default=parser.get_default(\"timeout_wait\"))\n    seed: int = parser.get_default(\"seed\")\n    max_lifetime_restarts: int = parser.get_default(\"max_lifetime_restarts\")\n    restarts_rate_limit_n: int = parser.get_default(\"restarts_rate_limit_n\")\n    restarts_rate_limit_period_s: int = parser.get_default(\n        \"restarts_rate_limit_period_s\"\n    )\n\n    @num_envs.validator\n    def validate_num_envs(self, attribute, value):\n        if value > 1 and self.env_path is None:\n            raise ValueError(\"num_envs must be 1 if env_path is not set.\")\n\n    @num_areas.validator\n    def validate_num_area(self, attribute, value):\n        if value <= 0:\n            raise ValueError(\"num_areas must be set to a positive number >= 1.\")\n\n\n@attr.s(auto_attribs=True)\nclass EngineSettings:\n    width: int = parser.get_default(\"width\")\n    height: int = parser.get_default(\"height\")\n    quality_level: int = parser.get_default(\"quality_level\")\n    time_scale: float = parser.get_default(\"time_scale\")\n    target_frame_rate: int = parser.get_default(\"target_frame_rate\")\n    capture_frame_rate: int = parser.get_default(\"capture_frame_rate\")\n    no_graphics: bool = parser.get_default(\"no_graphics\")\n    no_graphics_monitor: bool = parser.get_default(\"no_graphics_monitor\")\n","sourceCodeStart":813,"sourceCodeEnd":849,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents/mlagents/trainers/settings.py#L813-L849","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set num_envs: 1 in the config when training in the Unity editor (no env_path).","Alternatively, provide env_path pointing to a built environment executable and keep num_envs > 1.","Use --num-envs CLI flag consistently with whether --env is supplied."],"exampleFix":"# before (editor training)\nenv: null\nnum_envs: 8\n# after\nenv: null\nnum_envs: 1","handlingStrategy":"validation","validationCode":"if opts.env_path is None and opts.num_envs > 1:\n    raise ValueError('num_envs must be 1 when training without an env build')","typeGuard":"def valid_num_envs(env_path, num_envs):\n    return env_path is not None or num_envs == 1","tryCatchPattern":"try:\n    run_training(run_options)\nexcept ValueError as e:\n    if 'num_envs must be 1' in str(e):\n        run_options.num_envs = 1\n        run_training(run_options)","preventionTips":["Set num_envs: 1 for editor training; only raise it with an env build","Don't blindly copy num_envs from example configs","Wrap run_options construction in validation before launching training"],"tags":["config","environment","ml-agents"],"backgroundTag":"invalid-config-value","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}