{"record":{"id":"5f952932df89fd00","repo":"Unity-Technologies/ml-agents","slug":"the-engineconfigurationchannel-received-a-message","errorCode":null,"errorMessage":"The EngineConfigurationChannel received a message from Unity, this should not have happened.","messagePattern":"The EngineConfigurationChannel received a message from Unity, this should not have happened\\.","errorType":"exception","errorClass":"UnityCommunicationException","httpStatus":null,"severity":"error","filePath":"ml-agents-envs/mlagents_envs/side_channel/engine_configuration_channel.py","lineNumber":54,"sourceCode":"    class ConfigurationType(IntEnum):\n        SCREEN_RESOLUTION = 0\n        QUALITY_LEVEL = 1\n        TIME_SCALE = 2\n        TARGET_FRAME_RATE = 3\n        CAPTURE_FRAME_RATE = 4\n\n    def __init__(self) -> None:\n        super().__init__(uuid.UUID(\"e951342c-4f7e-11ea-b238-784f4387d1f7\"))\n\n    def on_message_received(self, msg: IncomingMessage) -> None:\n        \"\"\"\n        Is called by the environment to the side channel. Can be called\n        multiple times per step if multiple messages are meant for that\n        SideChannel.\n        Note that Python should never receive an engine configuration from\n        Unity\n        \"\"\"\n        raise UnityCommunicationException(\n            \"The EngineConfigurationChannel received a message from Unity, \"\n            + \"this should not have happened.\"\n        )\n\n    def set_configuration_parameters(\n        self,\n        width: Optional[int] = None,\n        height: Optional[int] = None,\n        quality_level: Optional[int] = None,\n        time_scale: Optional[float] = None,\n        target_frame_rate: Optional[int] = None,\n        capture_frame_rate: Optional[int] = None,\n    ) -> None:\n        \"\"\"\n        Sets the engine configuration. Takes as input the configurations of the\n        engine.\n        :param width: Defines the width of the display. (Must be set alongside height)\n        :param height: Defines the height of the display. (Must be set alongside width)","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents-envs/mlagents_envs/side_channel/engine_configuration_channel.py#L36-L72","documentation":"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.","triggerScenarios":"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.","commonSituations":"Mismatched ML-Agents versions between Unity package and Python; a modified Unity environment that writes to the wrong channel.","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."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"# EngineConfigurationChannel is send-only; ensure no custom Unity code uses its channel id\n# UUID e951342c-6f3e-11ea-bc55-0242ac130003 in the Unity project","typeGuard":null,"tryCatchPattern":"from mlagents_envs.exception import UnityCommunicationException\ntry:\n    env.step()\nexcept UnityCommunicationException as e:\n    print(\"Unexpected message on EngineConfigurationChannel; check versions:\", e)","preventionTips":["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"],"tags":["unity","side-channel","version-mismatch"],"backgroundTag":"side-channel-version-mismatch","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}