Unity-Technologies/ml-agents · error · UnityGymException

There can only be one behavior in a UnityEnvironment if it i

Error message

There can only be one behavior in a UnityEnvironment if it is wrapped in a gym.

What it means

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.

Source

Thrown at ml-agents-envs/mlagents_envs/envs/unity_gym_env.py:68

        """
        self._env = unity_env

        # Take a single step so that the brain information will be sent over
        if not self._env.behavior_specs:
            self._env.step()

        self.visual_obs = None

        # Save the step result from the last time all Agents requested decisions.
        self._previous_decision_step: Optional[DecisionSteps] = None
        self._flattener = None
        # Hidden flag used by Atari environments to determine if the game is over
        self.game_over = False
        self._allow_multiple_obs = allow_multiple_obs

        # Check brain configuration
        if len(self._env.behavior_specs) != 1:
            raise UnityGymException(
                "There can only be one behavior in a UnityEnvironment "
                "if it is wrapped in a gym."
            )

        self.name = list(self._env.behavior_specs.keys())[0]
        self.group_spec = self._env.behavior_specs[self.name]

        if self._get_n_vis_obs() == 0 and self._get_vec_obs_size() == 0:
            raise UnityGymException(
                "There are no observations provided by the environment."
            )

        if not self._get_n_vis_obs() >= 1 and uint8_visual:
            logger.warning(
                "uint8_visual was set to true, but visual observations are not in use. "
                "This setting will not have any effect."
            )
        else:

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Rebuild/reconfigure the Unity scene so all Agents share a single Behavior name (one BehaviorSpec).
2. Use mlagents_envs.envs.UnityEnvironment directly with behavior-spec-keyed step/reset instead of the gym wrapper.
3. Check len(env.behavior_specs) and print keys before wrapping to identify offending behaviors.
4. Remove or disable extra Agents with unique Behavior Names in the scene.

Example fix

// before
env = UnityGymEnv(UnityEnvironment(file_name='multi_behavior_app'))
// after
unity_env = UnityEnvironment(file_name='single_behavior_app')
assert len(unity_env.behavior_specs) == 1
env = UnityGymEnv(unity_env)

unity_env = UnityEnvironment(file_name='app')
if len(unity_env.behavior_specs) != 1:
    raise ValueError(f"Need exactly 1 behavior, got {list(unity_env.behavior_specs)}")
env = UnityGymEnv(unity_env)

def is_single_behavior(env) -> bool:
    return len(getattr(env, 'behavior_specs', {})) == 1

try:
    env = UnityGymEnv(unity_env)
except UnityGymException as e:
    logger.error("gym wrap failed: %s; behaviors=%s", e, list(unity_env.behavior_specs))

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• There are no observations provided by the environment.
• The gym wrapper does not provide explicit support for both d
• There can only be one Agent in the environment but {n_agents
• Action spaces with both continuous and discrete actions are
• The number of training areas that you have specified exceeds

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