Unity-Technologies/ml-agents · error · UnityActionException

The group {behavior_name} does not correspond to an existing

Error message

The group {behavior_name} does not correspond to an existing agent group in the environment

What it means

UnityActionException raised by UnityEnvironment._assert_behavior_exists when the given behavior_name is not a key in self._env_specs, i.e. that agent group does not exist in the current environment state. It is used as a guard by set_actions, set_action_for_agent, and get_steps to reject unknown behaviors before acting on them.

Source

Thrown at ml-agents-envs/mlagents_envs/environment.py:362

                    group_name
                ].action_spec.empty_action(n_agents)
        step_input = self._generate_step_input(self._env_actions)
        with hierarchical_timer("communicator.exchange"):
            outputs = self._communicator.exchange(step_input, self._poll_process)
        if outputs is None:
            raise UnityCommunicatorStoppedException("Communicator has exited.")
        self._update_behavior_specs(outputs)
        rl_output = outputs.rl_output
        self._update_state(rl_output)
        self._env_actions.clear()

    @property
    def behavior_specs(self) -> MappingType[str, BehaviorSpec]:
        return BehaviorMapping(self._env_specs)

    def _assert_behavior_exists(self, behavior_name: str) -> None:
        if behavior_name not in self._env_specs:
            raise UnityActionException(
                f"The group {behavior_name} does not correspond to an existing "
                f"agent group in the environment"
            )

    def set_actions(self, behavior_name: BehaviorName, action: ActionTuple) -> None:
        self._assert_behavior_exists(behavior_name)
        if behavior_name not in self._env_state:
            return
        action_spec = self._env_specs[behavior_name].action_spec
        num_agents = len(self._env_state[behavior_name][0])
        action = action_spec._validate_action(action, num_agents, behavior_name)
        self._env_actions[behavior_name] = action

    def set_action_for_agent(
        self, behavior_name: BehaviorName, agent_id: AgentId, action: ActionTuple
    ) -> None:
        self._assert_behavior_exists(behavior_name)
        if behavior_name not in self._env_state:

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Print/list env.behavior_specs.keys() and use the exact behavior name string.
2. Call env.reset() (or step once) before querying/setting actions so behavior specs are populated.
3. Fix typos and match the Behavior Name parameter set on the Agent in the Unity scene.
4. Guard calls: only use behaviors present in the current specs mapping.

Example fix

// before
env.set_actions('Crawler', action_tuple)  # behavior renamed -> UnityActionException

// after
env.reset()
for behavior in env.behavior_specs:
    env.set_actions(behavior, action_tuple)

env.reset()
behavior_name = '3DBall'
if behavior_name not in env.behavior_specs:
    raise ValueError(
        f'{behavior_name!r} not found. Available: {list(env.behavior_specs)}'
    )
env.set_actions(behavior_name, action_tuple)

from mlagents_envs.exception import UnityActionException
try:
    steps = env.get_steps(behavior_name)
except UnityActionException as e:
    print(f'{e}. Available behaviors: {list(env.behavior_specs)}')
    raise

When it happens

Trigger: Calling env.set_actions('<Behavior>', action), env.set_action_for_agent(...), or env.get_steps('<Behavior>') with a behavior name that is not present in env.behavior_specs (typo, behavior removed, or environment not stepped/reset yet so specs are empty).

Common situations: Hardcoded behavior names that changed after renaming the Behavior Name parameter in Unity; reading specs before the first reset so no behaviors are registered; a behavior only appears when its agents request a decision.

Related errors

• Expected parentIndices[0] to be -1, got {parentIndices[0]}
• The behavior {name} needs a continuous input of dimension {_
• agent_id {} is did not request a decision at the previous st
• You cannot set the width/height of the screen resolution wit
• When using a recurrent network, memory size must be greater

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