Unity-Technologies/ml-agents · error · UnityCommunicationException

The EngineConfigurationChannel received a message from Unity

Error message

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

What it means

EngineConfigurationChannel is outbound-only: Python sends engine settings (time scale, resolution) to Unity, and Unity should never send engine configuration back. Receiving a message means a protocol/version violation, so on_message_received raises UnityCommunicationException.

Source

Thrown at ml-agents-envs/mlagents_envs/side_channel/engine_configuration_channel.py:54

    class ConfigurationType(IntEnum):
        SCREEN_RESOLUTION = 0
        QUALITY_LEVEL = 1
        TIME_SCALE = 2
        TARGET_FRAME_RATE = 3
        CAPTURE_FRAME_RATE = 4

    def __init__(self) -> None:
        super().__init__(uuid.UUID("e951342c-4f7e-11ea-b238-784f4387d1f7"))

    def on_message_received(self, msg: IncomingMessage) -> None:
        """
        Is called by the environment to the side channel. Can be called
        multiple times per step if multiple messages are meant for that
        SideChannel.
        Note that Python should never receive an engine configuration from
        Unity
        """
        raise UnityCommunicationException(
            "The EngineConfigurationChannel received a message from Unity, "
            + "this should not have happened."
        )

    def set_configuration_parameters(
        self,
        width: Optional[int] = None,
        height: Optional[int] = None,
        quality_level: Optional[int] = None,
        time_scale: Optional[float] = None,
        target_frame_rate: Optional[int] = None,
        capture_frame_rate: Optional[int] = None,
    ) -> None:
        """
        Sets the engine configuration. Takes as input the configurations of the
        engine.
        :param width: Defines the width of the display. (Must be set alongside height)
        :param height: Defines the height of the display. (Must be set alongside width)

View on GitHub (pinned to 3ecb446f75)

Solutions

Align the Unity ML-Agents package version with the Python mlagents_envs version.
Check the Unity environment for custom code writing to the EngineConfigurationChannel's channel id and remove it.
Update both sides to a matching supported release (e.g. pip install mlagents==<unity package version>).
Catch UnityCommunicationException around env.step()/reset() and report the version pair.

Defensive patterns

Strategy: try-catch

Validate before calling

# EngineConfigurationChannel is send-only; ensure no custom Unity code uses its channel id
# UUID e951342c-6f3e-11ea-bc55-0242ac130003 in the Unity project

Try / catch

from mlagents_envs.exception import UnityCommunicationException
try:
    env.step()
except UnityCommunicationException as e:
    print("Unexpected message on EngineConfigurationChannel; check versions:", e)

Prevention

Align Unity package and Python mlagents_envs versions
Never write to built-in channel ids from custom Unity code
Smoke-test env.step() once after upgrading either side
Log Unity python_api / package version at startup

When it happens

Trigger: env.step()/reset() when Unity returns data on the engine-configuration side channel (UUID e951342c-6f3e-11ea-bc55-0242ac130003), e.g. a custom or wrong-version Unity build echoing engine config.

Common situations: Mismatched ML-Agents versions between Unity package and Python; a modified Unity environment that writes to the wrong channel.

Related errors

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