Unity-Technologies/ml-agents · error · UnityCommunicationException

UnityEnvironment worker: send failed.

Error message

UnityEnvironment worker: send failed.

What it means

A sentinel error raised by UnityEnvWorker.send when writing an EnvironmentRequest to the multiprocessing Connection fails with BrokenPipeError or EOFError. It means the child worker process hosting the UnityEnvironment has died or closed its end of the pipe (e.g. Unity crashed or exited), so the parent can no longer send it commands; the underlying pipe failure is converted into this UnityCommunicationException.

Source

Thrown at ml-agents/mlagents/trainers/subprocess_env_manager.py:94

    environment_stats: EnvironmentStats


class UnityEnvWorker:
    def __init__(self, process: Process, worker_id: int, conn: Connection):
        self.process = process
        self.worker_id = worker_id
        self.conn = conn
        self.previous_step: EnvironmentStep = EnvironmentStep.empty(worker_id)
        self.previous_all_action_info: Dict[str, ActionInfo] = {}
        self.waiting = False
        self.closed = False

    def send(self, cmd: EnvironmentCommand, payload: Any = None) -> None:
        try:
            req = EnvironmentRequest(cmd, payload)
            self.conn.send(req)
        except (BrokenPipeError, EOFError):
            raise UnityCommunicationException("UnityEnvironment worker: send failed.")

    def recv(self) -> EnvironmentResponse:
        try:
            response: EnvironmentResponse = self.conn.recv()
            if response.cmd == EnvironmentCommand.ENV_EXITED:
                env_exception: Exception = response.payload
                raise env_exception
            return response
        except (BrokenPipeError, EOFError):
            raise UnityCommunicationException("UnityEnvironment worker: recv failed.")

    def request_close(self):
        try:
            self.conn.send(EnvironmentRequest(EnvironmentCommand.CLOSE))
        except (BrokenPipeError, EOFError):
            logger.debug(
                f"UnityEnvWorker {self.worker_id} got exception trying to close."
            )

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Check earlier logs for the root cause of the worker process dying (Unity editor/player crash, bad environment build, scene errors)
2. Ensure the Unity executable or editor build matches the ml-agents package version and contains the correct Academy/Behavior components
3. Enable worker restarts / reduce num_envs to isolate which environment instance is failing
4. If using --num-areas or multiple envs, verify ports and worker IDs do not collide

When it happens

Trigger: Thrown at ml-agents/mlagents/trainers/subprocess_env_manager.py:94 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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