Unity-Technologies/ml-agents · error · UnityCommunicationException

The DefaultTrainingAnalyticsSideChannel received a message f

Error message

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

What it means

DefaultTrainingAnalyticsSideChannel deliberately shares the TrainingAnalyticsSideChannel's UUID and is a Python-only placeholder: Unity should never send messages on this channel. Any incoming message means the Unity-side ML-Agents package is sending training analytics when the Python side expected none, so on_message_received raises UnityCommunicationException to signal a protocol mismatch.

Source

Thrown at ml-agents-envs/mlagents_envs/side_channel/default_training_analytics_side_channel.py:28

from google.protobuf.any_pb2 import Any


class DefaultTrainingAnalyticsSideChannel(SideChannel):
    """
    Side channel that sends information about the training to the Unity environment so it can be logged.
    """

    CHANNEL_ID = uuid.UUID("b664a4a9-d86f-5a5f-95cb-e8353a7e8356")

    def __init__(self) -> None:
        # >>> uuid.uuid5(uuid.NAMESPACE_URL, "com.unity.ml-agents/TrainingAnalyticsSideChannel")
        # UUID('b664a4a9-d86f-5a5f-95cb-e8353a7e8356')
        # We purposefully use the SAME side channel as the TrainingAnalyticsSideChannel

        super().__init__(DefaultTrainingAnalyticsSideChannel.CHANNEL_ID)

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

    def environment_initialized(self) -> None:
        # Tuple of (major, minor, patch)
        vi = sys.version_info

        msg = TrainingEnvironmentInitialized(
            python_version=f"{vi[0]}.{vi[1]}.{vi[2]}",
            mlagents_version="Custom",
            mlagents_envs_version=mlagents_envs.__version__,
            torch_version="Unknown",
            torch_device_type="Unknown",
        )
        any_message = Any()
        any_message.Pack(msg)

View on GitHub (pinned to 3ecb446f75)

Solutions

Use the correct side channel: pass TrainingAnalyticsSideChannel (or construct the env so the matching channel is registered) instead of the default one.
Ensure Unity ML-Agents package and Python mlagents/mlagents_envs versions match (e.g. both release 18).
Rebuild/replace the Unity environment binary with one that does not send training analytics if you intend to use the default channel.
Wrap env communication in try/except UnityCommunicationException and log the Unity version for diagnosis.

Example fix

// before
env = UnityEnvironment(file_name=env_path)
// after
from mlagents_envs.side_channel.training_analytics_side_channel import TrainingAnalyticsSideChannel
analytics = TrainingAnalyticsSideChannel()
env = UnityEnvironment(file_name=env_path, side_channels=[analytics])

Defensive patterns

Strategy: try-catch

Validate before calling

from mlagents_envs.side_channel.training_analytics_side_channel import TrainingAnalyticsSideChannel
# register the matching analytics channel so Unity's message is consumed, not rejected
side_channels = [ch for ch in side_channels if not isinstance(ch, type(default_channel))]

Try / catch

from mlagents_envs.exception import UnityCommunicationException
try:
    env.step()
except UnityCommunicationException as e:
    print("Unity sent on a Python-only side channel; check ML-Agents version match:", e)

Prevention

Keep Unity ML-Agents package and pip mlagents versions identical
Register TrainingAnalyticsSideChannel when the Unity build sends analytics
Don't send messages to Python-only side channels from custom Unity code
Test the env binary against your Python package version before long runs

When it happens

Trigger: Calling env.step()/reset() while the attached Unity environment sends a message on channel UUID b664a4a9-d86f-5a5f-95cb-e8353a7e8356 (e.g. a Unity build built with TrainingAnalytics enabled) instead of the expected DefaultTrainingAnalyticsSideChannel.

Common situations: Running an older/newer Unity ML-Agents plugin against mismatched mlagents_envs Python package; using the default (no-analytics) channel with an editor build configured to send training analytics.

Related errors

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