Unity-Technologies/ml-agents · error · UnityCommunicationException

The TrainingAnalyticsSideChannel received a message from Uni

Error message

The TrainingAnalyticsSideChannel received a message from Unity, this should not have happened.

What it means

TrainingAnalyticsSideChannel.on_message_received unconditionally raises UnityCommunicationException. This side channel is one-way (trainer sends analytics to Unity) and the Unity side should never send messages back; receiving one signals a protocol/communication error between the editor and the trainer process.

Source

Thrown at ml-agents/mlagents/trainers/training_analytics_side_channel.py:48

    __vendorKey: str = "unity.ml-agents"

    def __init__(self) -> None:
        # >>> uuid.uuid5(uuid.NAMESPACE_URL, "com.unity.ml-agents/TrainingAnalyticsSideChannel")
        # UUID('b664a4a9-d86f-5a5f-95cb-e8353a7e8356')
        # Use the same uuid as the parent side channel
        super().__init__()
        self.run_options: Optional[RunOptions] = None

    @classmethod
    def _hash(cls, data: str) -> str:
        res = hmac.new(
            cls.__vendorKey.encode("utf-8"), data.encode("utf-8"), hashlib.sha256
        ).hexdigest()
        return res

    def on_message_received(self, msg: IncomingMessage) -> None:
        raise UnityCommunicationException(
            "The TrainingAnalyticsSideChannel received a message from Unity, "
            "this should not have happened."
        )

    @classmethod
    def _sanitize_run_options(cls, config: RunOptions) -> Dict[str, Any]:
        res = copy.deepcopy(config.as_dict())

        # Filter potentially PII behavior names
        if "behaviors" in res and res["behaviors"]:
            res["behaviors"] = {cls._hash(k): v for (k, v) in res["behaviors"].items()}
            for (k, v) in res["behaviors"].items():
                if "init_path" in v and v["init_path"] is not None:
                    hashed_path = cls._hash(v["init_path"])
                    res["behaviors"][k]["init_path"] = hashed_path
                if "demo_path" in v and v["demo_path"] is not None:
                    hashed_path = cls._hash(v["demo_path"])
                    res["behaviors"][k]["demo_path"] = hashed_path

View on GitHub (pinned to 3ecb446f75)

Solutions

Align versions of the Python mlagents package and the Unity com.unity.ml-agents package (check release compatibility table)
Remove any custom code sending messages on the TrainingAnalytics channel GUID
Disable the training analytics side channel (e.g. via --no-graphics / analytics-related flags) if not needed
Reinstall matching mlagents/mlagents_envs versions (pip install mlagents==<matching version>)

Example fix

// before (custom code on analytics channel)
side_channel_manager.send_message(training_analytics_channel, msg)
// after
# remove the send; analytics channel is one-way (trainer -> Unity)

Defensive patterns

Strategy: try-catch

Validate before calling

import mlagents, importlib.metadata
print(importlib.metadata.version("mlagents"))
# Ensure this matches the com.unity.ml-agents package version in Unity

Try / catch

from mlagents_envs.exception import UnityCommunicationException
try:
    env.step()  # any side-channel message handling
except UnityCommunicationException as e:
    if "TrainingAnalyticsSideChannel" in str(e):
        logger.warning("Unity sent an unexpected analytics message; check package version match")
    else:
        raise

Prevention

Keep mlagents Python package and com.unity.ml-agents Unity package on matching versions
Never send messages from Unity on one-way (trainer-to-Unity) side channels
Do not reuse the TrainingAnalytics channel UUID for custom side channels
Update both sides together when upgrading ML-Agents

When it happens

Trigger: Unity sending a message on the TrainingAnalytics side channel, e.g. due to a mismatched or buggy side-channel implementation in the ml-agents-envs/commlabels versions, or custom editor code writing to the same channel UUID.

Common situations: Version mismatch between the ml-agents Python package and the com.unity.ml-agents Unity package; a custom fork or plugin reusing the analytics channel GUID; corrupted inter-process communication.

Related errors

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