Unity-Technologies/ml-agents · error · UnityCommunicatorStoppedException

Communicator has exited.

Error message

Communicator has exited.

What it means

UnityCommunicatorStoppedException raised in UnityEnvironment.reset when self._communicator.exchange returns None during a reset, meaning the communicator has exited and the Unity process is gone or the socket closed. The library can no longer exchange messages with the environment, so it stops with this error instead of returning stale data.

Source

Thrown at ml-agents-envs/mlagents_envs/environment.py:322

            if brain_name in output.agentInfos:
                agent_info_list = output.agentInfos[brain_name].value
                self._env_state[brain_name] = steps_from_proto(
                    agent_info_list, self._env_specs[brain_name]
                )
            else:
                self._env_state[brain_name] = (
                    DecisionSteps.empty(self._env_specs[brain_name]),
                    TerminalSteps.empty(self._env_specs[brain_name]),
                )
        self._side_channel_manager.process_side_channel_message(output.side_channel)

    def reset(self) -> None:
        if self._loaded:
            outputs = self._communicator.exchange(
                self._generate_reset_input(), self._poll_process
            )
            if outputs is None:
                raise UnityCommunicatorStoppedException("Communicator has exited.")
            self._update_behavior_specs(outputs)
            rl_output = outputs.rl_output
            self._update_state(rl_output)
            self._is_first_message = False
            self._env_actions.clear()
        else:
            raise UnityEnvironmentException("No Unity environment is loaded.")

    @timed
    def step(self) -> None:
        if self._is_first_message:
            return self.reset()
        if not self._loaded:
            raise UnityEnvironmentException("No Unity environment is loaded.")
        # fill the blanks for missing actions
        for group_name in self._env_specs:
            if group_name not in self._env_actions:
                n_agents = 0

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Inspect the Unity executable's stdout/stderr or its log files to find why it exited.
2. Recreate the UnityEnvironment after the communicator has stopped; it cannot be reused.
3. Check timeouts: increase timeout_wait if the environment is slow to start/respond.
4. Verify the build is a headless/server build appropriate for the machine (GPU/display drivers).

Example fix

// before
env = UnityEnvironment(file_name='env.x86_64')
for _ in range(10000):
    env.step()  # env crashed earlier -> UnityCommunicatorStoppedException

// after
env = UnityEnvironment(file_name='env.x86_64')
try:
    for _ in range(10000):
        env.step()
except UnityCommunicatorStoppedException:
    env.close()
    env = UnityEnvironment(file_name='env.x86_64')  # restart environment

if env is None:
    raise RuntimeError('UnityEnvironment was never initialized')
# Optionally verify the process is alive before exchanging (implementation-specific).

from mlagents_envs.exception import UnityCommunicatorStoppedException
try:
    env.reset()
except UnityCommunicatorStoppedException:
    env.close()
    env = UnityEnvironment(file_name='env.x86_64')  # relaunch; communicator cannot recover
    env.reset()

When it happens

Trigger: Calling env.reset() (directly or via the first env.step()) after the Unity executable has crashed, been closed by the user, or the socket/connection dropped; exchange(step_input, poll_process) returns None when the communicator detects the process exited.

Common situations: Unity build crashing mid-training (native error, OOM); user closing the game window; environment exiting due to an internal exception; timeout exceeded while waiting for a message causing the communicator to shut down.

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