{"record":{"id":"c934325ab16ecfe2","repo":"Unity-Technologies/ml-agents","slug":"the-unity-environment-took-too-long-to-respond-ma","errorCode":null,"errorMessage":"The Unity environment took too long to respond. Make sure that :\n\t The environment does not need user interaction to launch\n\t The Agents' Behavior Parameters > Behavior Type is set to \"Default\"\n\t The environment and the Python interface have compatible versions.\n\t If you're running on a headless server without graphics support, turn off display by either passing --no-graphics option or build your Unity executable as server build.","messagePattern":"The Unity environment took too long to respond\\. Make sure that :\n\t The environment does not need user interaction to launch\n\t The Agents' Behavior Parameters > Behavior Type is set to \"Default\"\n\t The environment and the Python interface have compatible versions\\.\n\t If you're running on a headless server without graphics support, turn off display by either passing --no-graphics option or build your Unity executable as server build\\.","errorType":"exception","errorClass":"UnityTimeOutException","httpStatus":null,"severity":"error","filePath":"ml-agents-envs/mlagents_envs/rpc_communicator.py","lineNumber":114,"sourceCode":"        us from hanging indefinitely in the case where the environment process has died or was not\n        launched.\n\n        Additionally, a callback can be passed to periodically check the state of the environment.\n        This is used to detect the case when the environment dies without cleaning up the connection,\n        so that we can stop sooner and raise a more appropriate error.\n        \"\"\"\n        deadline = time.monotonic() + self.timeout_wait\n        callback_timeout_wait = self.timeout_wait // 10\n        while time.monotonic() < deadline:\n            if self.unity_to_external.parent_conn.poll(callback_timeout_wait):\n                # Got an acknowledgment from the connection\n                return\n            if poll_callback:\n                # Fire the callback - if it detects something wrong, it should raise an exception.\n                poll_callback()\n\n        # Got this far without reading any data from the connection, so it must be dead.\n        raise UnityTimeOutException(\n            \"The Unity environment took too long to respond. Make sure that :\\n\"\n            \"\\t The environment does not need user interaction to launch\\n\"\n            '\\t The Agents\\' Behavior Parameters > Behavior Type is set to \"Default\"\\n'\n            \"\\t The environment and the Python interface have compatible versions.\\n\"\n            \"\\t If you're running on a headless server without graphics support, turn off display \"\n            \"by either passing --no-graphics option or build your Unity executable as server build.\"\n        )\n\n    def initialize(\n        self, inputs: UnityInputProto, poll_callback: Optional[PollCallback] = None\n    ) -> UnityOutputProto:\n        self.poll_for_timeout(poll_callback)\n        aca_param = self.unity_to_external.parent_conn.recv().unity_output\n        message = UnityMessageProto()\n        message.header.status = 200\n        message.unity_input.CopyFrom(inputs)\n        self.unity_to_external.parent_conn.send(message)\n        self.unity_to_external.parent_conn.recv()","sourceCodeStart":96,"sourceCodeEnd":132,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents-envs/mlagents_envs/rpc_communicator.py#L96-L132","documentation":"UnityTimeOutException is raised by RpcCommunicator.poll_for_timeout when gRPC polling completes without ever receiving data from the Unity side within the timeout window. The library assumes the Unity environment is dead, unresponsive, or was never launched correctly.","triggerScenarios":"initialize() or exchange() waiting past timeout_seconds for the first (or any) message from the Unity executable; the executable failed to start, is blocked on a dialog, or runs an incompatible communicator API version.","commonSituations":"Building the environment without checking 'Development build'; behavior parameters set to Inference-only while Python expects training messages; running on a headless server without --no-graphics or a server build so Unity hangs on graphics init; environment needs a manual click/license prompt to launch; version mismatch between ml-agents Python package and Unity package.","solutions":["Run with --no-graphics or build the executable as a server (headless) build when on a machine without a display.","Set Behavior Type to 'Default' in Behavior Parameters so the Academy connects to the external communicator.","Check that ml-agents-envs Python version and com.unity.ml-agents Unity package versions are compatible (both the same release line).","Launch the environment manually first to confirm it starts without user interaction (dialogs, sign-in, license activation), and increase timeout via UnityEnvironment(..., timeout_wait=...) if it's just slow to boot."],"exampleFix":"// before\nenv = UnityEnvironment(file_name=env_path)  # headless server -> UnityTimeOutException\n// after\nenv = UnityEnvironment(file_name=env_path, no_graphics=True, timeout_wait=120)","handlingStrategy":"retry","validationCode":"import os\n\ndef launch_should_succeed(file_name: str, no_graphics: bool) -> bool:\n    if no_graphics and os.environ.get(\"DISPLAY\") and not os.environ.get(\"HEADLESS_OK\"):\n        # headless flag on a machine WITH a display may still be fine, but warn\n        pass\n    return os.path.isfile(file_name)\n\n# also: assert executable exists and is executable before launching","typeGuard":"import os, stat\n\ndef is_executable_env(path: str) -> bool:\n    return os.path.isfile(path) and os.access(path, os.X_OK)","tryCatchPattern":"from mlagents_envs.exception import UnityTimeOutException\n\ntry:\n    env = UnityEnvironment(file_name=env_path, no_graphics=True, timeout_wait=300)\nexcept UnityTimeOutException:\n    # retry once with longer timeout / no-graphics\n    env = UnityEnvironment(file_name=env_path, no_graphics=True, timeout_wait=600)","preventionTips":["On headless servers always pass no_graphics=True or build a server build.","Keep Behavior Type = 'Default' in Behavior Parameters.","Pin com.unity.ml-agents and mlagents-envs to the same release version.","Increase timeout_wait for slow-loading environments; launch the executable manually once to verify no dialogs block startup."],"tags":["python","unity-ml-agents","timeout","grpc"],"backgroundTag":"environment-connection-timeout","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}