Unity-Technologies/ml-agents · error · UnityAgentsException

There was a problem reading a message in a SideChannel. Plea

Error message

There was a problem reading a message in a SideChannel. Please make sure the version of MLAgents in Unity is compatible with the Python version. Original error : {ex.Message}

What it means

SideChannelManager.ProcessSideChannelData parses incoming binary messages (16-byte GUID + int32 length + payload). Any exception while reading (malformed/truncated data, wrong byte layout) is wrapped and rethrown as UnityAgentsException telling you the Unity and Python ML-Agents versions are likely incompatible. The real cause is preserved in the 'Original error' text.

Source

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

                return;
            }
            using (var memStream = new MemoryStream(dataReceived))
            {
                using (var binaryReader = new BinaryReader(memStream))
                {
                    while (memStream.Position < memStream.Length)
                    {
                        Guid channelId = Guid.Empty;
                        byte[] message = null;
                        try
                        {
                            channelId = new Guid(binaryReader.ReadBytes(16));
                            var messageLength = binaryReader.ReadInt32();
                            message = binaryReader.ReadBytes(messageLength);
                        }
                        catch (Exception ex)
                        {
                            throw new UnityAgentsException(
                                "There was a problem reading a message in a SideChannel. Please make sure the " +
                                "version of MLAgents in Unity is compatible with the Python version. Original error : "
                                + ex.Message);
                        }
                        if (sideChannels.ContainsKey(channelId))
                        {
                            sideChannels[channelId].ProcessMessage(message);
                        }
                        else
                        {
                            // Don't recognize this ID, but cache it in case the SideChannel that can handle
                            // it is registered before the next call to ProcessSideChannelData.
                            s_CachedMessages.Enqueue(new CachedSideChannelMessage
                            {
                                ChannelId = channelId,
                                Message = message
                            });
                        }

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Align versions: use matching ml-agents and ml-agents-envs package versions on the Python side and the ML-Agents Unity package release on the C# side (check release notes for compatibility).
2. Read the 'Original error : ...' text in the message to identify the concrete parse failure (e.g. end-of-stream vs invalid GUID).
3. If using custom side channels, verify the Python and C# sides write/read the same byte format (Guid 16 bytes, int32 length, payload).
4. Re-export/rebuild the Unity environment so the built binary matches the installed Python packages.

Example fix

# before
pip install mlagents-envs  # latest, may mismatch Unity package version
# after
pip install mlagents==0.30.0 mlagents-envs==0.30.0  # match Unity ML-Agents release

# Python
import mlagents_envs, sys
# verify installed version matches the Unity ML-Agents release notes
print(mlagents_envs.__version__)

try:
    env.step()
except UnityEnvironmentException as e:
    if "SideChannel" in str(e):
        check_versions_and_rebuild(); # align pip packages with Unity plugin
    raise

When it happens

Trigger: Python side sends side-channel bytes whose layout doesn't match what the C# reader expects — wrong header size, corrupted or truncated stream, or a Python mlagents-envs version encoding messages differently than the Unity plugin expects.

Common situations: Mismatched ml-agents / ml-agents-envs versions between the Python trainer and the Unity project; a custom Python side channel writing a nonstandard payload framing; network/pipe corruption between communicator processes.

Related errors

• StatsSideChannel should never receive messages.
• API versions of demonstration are incompatible.
• Variable Length Observations are not supported by the traine
• A side channel with id {channelId} is already registered. Yo
• The DefaultTrainingAnalyticsSideChannel received a message f

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