{"record":{"id":"1b4cb1c660e40a06","repo":"Unity-Technologies/ml-agents","slug":"there-can-only-be-one-behavior-in-a-unityenvironme","errorCode":null,"errorMessage":"There can only be one behavior in a UnityEnvironment if it is wrapped in a gym.","messagePattern":"There can only be one behavior in a UnityEnvironment if it is wrapped in a gym\\.","errorType":"exception","errorClass":"UnityGymException","httpStatus":null,"severity":"error","filePath":"ml-agents-envs/mlagents_envs/envs/unity_gym_env.py","lineNumber":68,"sourceCode":"        \"\"\"\n        self._env = unity_env\n\n        # Take a single step so that the brain information will be sent over\n        if not self._env.behavior_specs:\n            self._env.step()\n\n        self.visual_obs = None\n\n        # Save the step result from the last time all Agents requested decisions.\n        self._previous_decision_step: Optional[DecisionSteps] = None\n        self._flattener = None\n        # Hidden flag used by Atari environments to determine if the game is over\n        self.game_over = False\n        self._allow_multiple_obs = allow_multiple_obs\n\n        # Check brain configuration\n        if len(self._env.behavior_specs) != 1:\n            raise UnityGymException(\n                \"There can only be one behavior in a UnityEnvironment \"\n                \"if it is wrapped in a gym.\"\n            )\n\n        self.name = list(self._env.behavior_specs.keys())[0]\n        self.group_spec = self._env.behavior_specs[self.name]\n\n        if self._get_n_vis_obs() == 0 and self._get_vec_obs_size() == 0:\n            raise UnityGymException(\n                \"There are no observations provided by the environment.\"\n            )\n\n        if not self._get_n_vis_obs() >= 1 and uint8_visual:\n            logger.warning(\n                \"uint8_visual was set to true, but visual observations are not in use. \"\n                \"This setting will not have any effect.\"\n            )\n        else:","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents-envs/mlagents_envs/envs/unity_gym_env.py#L50-L86","documentation":"UnityGymException thrown by the UnityGymEnv gym wrapper's __init__ when the underlying UnityEnvironment exposes more than one behavior (BehaviorSpec). The gym API models a single-agent, single-action-space environment, so a multi-behavior Unity environment cannot be wrapped.","triggerScenarios":"Constructing UnityGymEnv(unity_env) where unity_env.behavior_specs has len != 1 — i.e. the Unity build contains 0 or 2+ Behaviors (multiple Agent configurations with different Behavior Names).","commonSituations":"Wrapping a Unity build that contains several RL Agents each with a distinct Behavior name; using a curriculum/multi-agent scene with the gym wrapper; passing the wrong executable for a single-agent benchmark.","solutions":["Rebuild/reconfigure the Unity scene so all Agents share a single Behavior name (one BehaviorSpec).","Use mlagents_envs.envs.UnityEnvironment directly with behavior-spec-keyed step/reset instead of the gym wrapper.","Check len(env.behavior_specs) and print keys before wrapping to identify offending behaviors.","Remove or disable extra Agents with unique Behavior Names in the scene."],"exampleFix":"// before\nenv = UnityGymEnv(UnityEnvironment(file_name='multi_behavior_app'))\n// after\nunity_env = UnityEnvironment(file_name='single_behavior_app')\nassert len(unity_env.behavior_specs) == 1\nenv = UnityGymEnv(unity_env)","handlingStrategy":"validation","validationCode":"unity_env = UnityEnvironment(file_name='app')\nif len(unity_env.behavior_specs) != 1:\n    raise ValueError(f\"Need exactly 1 behavior, got {list(unity_env.behavior_specs)}\")\nenv = UnityGymEnv(unity_env)","typeGuard":"def is_single_behavior(env) -> bool:\n    return len(getattr(env, 'behavior_specs', {})) == 1","tryCatchPattern":"try:\n    env = UnityGymEnv(unity_env)\nexcept UnityGymException as e:\n    logger.error(\"gym wrap failed: %s; behaviors=%s\", e, list(unity_env.behavior_specs))","preventionTips":["Check len(env.behavior_specs) == 1 before wrapping","Keep one Behavior name across all Agents in single-agent scenes","Use the raw UnityEnvironment API for multi-behavior builds"],"tags":["gym","unity-environment","configuration"],"backgroundTag":"multiple-behaviors-unsupported","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}