Unity-Technologies/ml-agents · error · UnityAgentsException

Agent is already registered with a group. Unregister it firs

Error message

Agent is already registered with a group. Unregister it first.

What it means

The Agent's group registration property throws UnityAgentsException when the agent already belongs to a group (m_GroupId != 0) and is assigned a different group id without being unregistered first. Group ids are immutable once set to protect the integrity of multi-agent group training.

Source

Thrown at com.unity.ml-agents/Runtime/Agent.cs:1431

            m_ActuatorManager.UpdateActions(actions);
        }

        internal void SetMultiAgentGroup(IMultiAgentGroup multiAgentGroup)
        {
            if (multiAgentGroup == null)
            {
                m_GroupId = 0;
            }
            else
            {
                var newGroupId = multiAgentGroup.GetId();
                if (m_GroupId == 0 || m_GroupId == newGroupId)
                {
                    m_GroupId = newGroupId;
                }
                else
                {
                    throw new UnityAgentsException("Agent is already registered with a group. Unregister it first.");
                }
            }
        }
    }
}

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Unregister the agent from its current group before assigning a new GroupId
2. Reuse the same GroupId if the agent's team membership hasn't actually changed
3. Reset the agent's group id to 0 (or recreate the agent) between episodes

Example fix

// before
agent.GroupId = 5; // agent already in group 2
// after
agentManager.UnregisterAgent(agent);
agent.GroupId = 5;

if (agent.GroupId == 0 || agent.GroupId == newGroupId) {
    agent.GroupId = newGroupId;
} else {
    // unregister from current group first
}

bool CanJoinGroup(Agent a, int g) => a.GroupId == 0 || a.GroupId == g;

try { agent.GroupId = newGroupId; } catch (UnityAgentsException e) { Debug.LogError(e.Message); }

When it happens

Trigger: Setting agent.GroupId (or changing it) to a value different from the current m_GroupId when m_GroupId != 0 — reassigning an agent from one group to another at runtime.

Common situations: Dynamically re-teaming agents mid-episode in multi-agent scenarios; spawning/recycling agents that retain a stale group id from a previous episode.

Related errors

• Call to SendInfoToBrain when Agent hasn't been initialized.P
• Index out of bounds, expected a number between 0 and {Length
• Enumerator not started.
• Enumerator has reached the end already.
• Action spaces with both continuous and discrete actions are

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