Unity-Technologies/ml-agents · error · UnityTimeOutException

The Unity environment took too long to respond. Make sure th

Error message

The Unity environment took too long to respond. Make sure that :
	 The environment does not need user interaction to launch
	 The Agents' Behavior Parameters > Behavior Type is set to "Default"
	 The environment and the Python interface have compatible versions.
	 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.

What it means

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.

Source

Thrown at ml-agents-envs/mlagents_envs/rpc_communicator.py:114

        us from hanging indefinitely in the case where the environment process has died or was not
        launched.

        Additionally, a callback can be passed to periodically check the state of the environment.
        This is used to detect the case when the environment dies without cleaning up the connection,
        so that we can stop sooner and raise a more appropriate error.
        """
        deadline = time.monotonic() + self.timeout_wait
        callback_timeout_wait = self.timeout_wait // 10
        while time.monotonic() < deadline:
            if self.unity_to_external.parent_conn.poll(callback_timeout_wait):
                # Got an acknowledgment from the connection
                return
            if poll_callback:
                # Fire the callback - if it detects something wrong, it should raise an exception.
                poll_callback()

        # Got this far without reading any data from the connection, so it must be dead.
        raise UnityTimeOutException(
            "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."
        )

    def initialize(
        self, inputs: UnityInputProto, poll_callback: Optional[PollCallback] = None
    ) -> UnityOutputProto:
        self.poll_for_timeout(poll_callback)
        aca_param = self.unity_to_external.parent_conn.recv().unity_output
        message = UnityMessageProto()
        message.header.status = 200
        message.unity_input.CopyFrom(inputs)
        self.unity_to_external.parent_conn.send(message)
        self.unity_to_external.parent_conn.recv()

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Run with --no-graphics or build the executable as a server (headless) build when on a machine without a display.
2. Set Behavior Type to 'Default' in Behavior Parameters so the Academy connects to the external communicator.
3. Check that ml-agents-envs Python version and com.unity.ml-agents Unity package versions are compatible (both the same release line).
4. 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.

Example fix

// before
env = UnityEnvironment(file_name=env_path)  # headless server -> UnityTimeOutException
// after
env = UnityEnvironment(file_name=env_path, no_graphics=True, timeout_wait=120)

import os

def launch_should_succeed(file_name: str, no_graphics: bool) -> bool:
    if no_graphics and os.environ.get("DISPLAY") and not os.environ.get("HEADLESS_OK"):
        # headless flag on a machine WITH a display may still be fine, but warn
        pass
    return os.path.isfile(file_name)

# also: assert executable exists and is executable before launching

import os, stat

def is_executable_env(path: str) -> bool:
    return os.path.isfile(path) and os.access(path, os.X_OK)

from mlagents_envs.exception import UnityTimeOutException

try:
    env = UnityEnvironment(file_name=env_path, no_graphics=True, timeout_wait=300)
except UnityTimeOutException:
    # retry once with longer timeout / no-graphics
    env = UnityEnvironment(file_name=env_path, no_graphics=True, timeout_wait=600)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Couldn't start socket communication because worker number {}
• Compressed observation and its mapping had different number
• Invalid Compressed Channel Mapping: the mapping {mappings} d
• Invalid Compressed Channel Mapping: the mapping has index la
• Observation at index={obs_index} for agent with id={agent_in

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