Unity-Technologies/ml-agents · error · UnityAgentsException

A side channel with id {channelId} is already registered. Yo

Error message

A side channel with id {channelId} is already registered. You cannot register multiple side channels of the same id.

What it means

SideChannelManager.RegisterSideChannel stores side channels by their UUID channel id in a single registry; each id may only be registered once. Registering a second SideChannel whose ChannelId GUID equals an existing one throws UnityAgentsException. This prevents messages from being ambiguously routed between channels.

Source

Thrown at com.unity.ml-agents/Runtime/SideChannels/SideChannelManager.cs:44

        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
        static void ResetStaticsOnLoad()
        {
            s_RegisteredChannels = new Dictionary<Guid, SideChannel>();
        }
#endif
        /// <summary>
        /// Register a side channel to begin sending and receiving messages. This method is
        /// available for environments that have custom side channels. All built-in side
        /// channels within the ML-Agents Toolkit are managed internally and do not need to
        /// be explicitly registered/unregistered. A side channel may only be registered once.
        /// </summary>
        /// <param name="sideChannel">The side channel to register.</param>
        public static void RegisterSideChannel(SideChannel sideChannel)
        {
            var channelId = sideChannel.ChannelId;
            if (s_RegisteredChannels.ContainsKey(channelId))
            {
                throw new UnityAgentsException(
                    $"A side channel with id {channelId} is already registered. " +
                    "You cannot register multiple side channels of the same id.");
            }

            // Process any messages that we've already received for this channel ID.
            var numMessages = s_CachedMessages.Count;
            for (var i = 0; i < numMessages; i++)
            {
                var cachedMessage = s_CachedMessages.Dequeue();
                if (channelId == cachedMessage.ChannelId)
                {
                    sideChannel.ProcessMessage(cachedMessage.Message);
                }
                else
                {
                    s_CachedMessages.Enqueue(cachedMessage);
                }
            }

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Register each channel id only once — keep a single shared instance of each channel type and reuse it.
2. Generate a unique GUID for your custom side channel (e.g. new System.Guid("...") with a freshly generated value) instead of reusing one from another channel.
3. UnregisterSideChannel the old instance before registering a new one with the same id, if replacement is intended.

Example fix

// before
var stats1 = new StatsSideChannel();
var stats2 = new StatsSideChannel(); // same ChannelId GUID
SideChannelManager.RegisterSideChannel(stats1);
SideChannelManager.RegisterSideChannel(stats2); // throws
// after
var stats = new StatsSideChannel();
SideChannelManager.RegisterSideChannel(stats); // one instance only

// C#
if (SideChannelManager.GetSideChannelIds().Contains(myChannel.ChannelId))
    return; // already registered

try { SideChannelManager.RegisterSideChannel(channel); }
catch (UnityAgentsException e) { Debug.LogWarning($"Channel {channel.ChannelId} already registered"); }

When it happens

Trigger: Calling RegisterSideChannel (or creating a UnityEnvironment/RpcCommunicator that auto-registers) with a side channel whose ChannelId GUID is already in s_RegisteredChannels — e.g. two instances of the same channel type, or a custom channel reusing a built-in's GUID.

Common situations: Adding the same StatsSideChannel/EngineConfigurationChannel instance twice; constructing two UnityEnvironment objects over the same registry and registering duplicate channels; copying a built-in channel class without changing its hardcoded ChannelId GUID.

Related errors

• There was a problem reading a message in a SideChannel. Plea
• StatsSideChannel should never receive messages.
• Index out of bounds, expected a number between 0 and {Length
• Enumerator not started.
• Enumerator has reached the end already.

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