Unity-Technologies/ml-agents · error · UnityCommunicationException

UnityEnvironment worker: recv failed.

Error message

UnityEnvironment worker: recv failed.

What it means

A sentinel error raised by UnityEnvWorker.recv when reading an EnvironmentResponse from the multiprocessing Connection raises BrokenPipeError or EOFError. It indicates the child worker process owning the UnityEnvironment is gone (crashed or exited), so its end of the pipe no longer exists; the raw pipe exception is wrapped into this UnityCommunicationException for uniform handling by the env manager.

Source

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

        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."
            )
            pass


def worker(
    parent_conn: Connection,
    step_queue: Queue,
    pickled_env_factory: str,
    worker_id: int,
    run_options: RunOptions,
    log_level: int = logging_util.INFO,

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Inspect stderr from the worker process to find why Unity exited (crash, build mismatch, fatal Unity log error)
2. Verify the environment binary path and that the build was made with a compatible ml-agents Unity package
3. Run with a single environment (num_envs=1) to reproduce and capture the root failure
4. Restart training after fixing the underlying Unity-side crash; the pipe error is only a symptom

When it happens

Trigger: Thrown at ml-agents/mlagents/trainers/subprocess_env_manager.py:104 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/f220a02f232addca. Report an issue: GitHub.