Unity-Technologies/ml-agents · error · UnityEnvironmentException

The message received by the side channel {} was unexpectedly

Error message

The message received by the side channel {} was unexpectedly short. Make sure your Unity Environment sending side channel data properly.

What it means

After unpacking the length header, the code slices message_data from the byte stream; if the remaining bytes are fewer than the declared message_len, the Unity side produced truncated side-channel data, so UnityEnvironmentException naming the channel id is raised.

Source

Thrown at ml-agents-envs/mlagents_envs/side_channel/side_channel_manager.py:35

        :param data: The packed message sent by Unity
        """
        offset = 0
        while offset < len(data):
            try:
                channel_id = uuid.UUID(bytes_le=bytes(data[offset : offset + 16]))
                offset += 16
                (message_len,) = struct.unpack_from("<i", data, offset)
                offset = offset + 4
                message_data = data[offset : offset + message_len]
                offset = offset + message_len
            except (struct.error, ValueError, IndexError):
                raise UnityEnvironmentException(
                    "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."
                )
            if len(message_data) != message_len:
                raise UnityEnvironmentException(
                    "The message received by the side channel {} was "
                    "unexpectedly short. Make sure your Unity Environment "
                    "sending side channel data properly.".format(channel_id)
                )
            if channel_id in self._side_channels_dict:
                incoming_message = IncomingMessage(message_data)
                self._side_channels_dict[channel_id].on_message_received(
                    incoming_message
                )
            else:
                get_logger(__name__).warning(
                    f"Unknown side channel data received. Channel type: {channel_id}."
                )

    def generate_side_channel_messages(self) -> bytearray:
        """
        Gathers the messages that the registered side channels will send to Unity
        and combines them into a single message ready to be sent.

View on GitHub (pinned to 3ecb446f75)

Solutions

Match Unity ML-Agents package version with the Python package version.
Audit any custom Unity side channels for wrong/oversized length writes.
Rebuild the Unity environment against the installed Python SDK.
Catch UnityEnvironmentException around env.step()/reset() and log the offending channel_id for triage.
Check for communication corruption (launching env locally vs remote, buffer sizes).

Example fix

// before
env.step()
// after
from mlagents_envs.exception import UnityEnvironmentException
try:
    env.step()
except UnityEnvironmentException as e:
    logging.error(f"Truncated side channel payload: {e}")  # verify Unity/Python ML-Agents versions

Defensive patterns

Strategy: try-catch

Validate before calling

# pre-check: ensure Unity build and Python SDK are from the same release train
import mlagents_envs
print(mlagents_envs.__version__)

Try / catch

from mlagents_envs.exception import UnityEnvironmentException
try:
    env.step()
except UnityEnvironmentException as e:
    logging.error("Short side-channel message; verify Unity env build and versions: %s", e)

Prevention

Rebuild Unity env with the SDK matching your Python install
Fix custom Unity side channels to write correct message lengths
Validate message framing when adding new side channels on the Unity side
Test one step/reset after any version bump

When it happens

Trigger: env.step()/reset() where a Unity message declares length N but the payload carries fewer than N bytes, typically from an incompatible or misbehaving Unity environment.

Common situations: Mixed Unity/Python ML-Agents versions; custom side channel in Unity writing incorrect message lengths; corrupted communication pipe.

Related errors

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