Unity-Technologies/ml-agents · error · UnityEnvironmentException

If the environment name is None, the worker-id must be 0 in

Error message

If the environment name is None, the worker-id must be 0 in order to connect with the Editor.

What it means

UnityEnvironment.__init__ throws UnityEnvironmentException when file_name is None (meaning: do not launch a binary, connect to an already-running environment such as the Unity Editor) but worker_id is nonzero. Only worker_id 0 is valid for Editor connection because the Editor listens on a single fixed channel. This guard exists purely to prevent connecting to a nonexistent Editor endpoint.

Source

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

        if side_channels is None:
            side_channels = []
        default_training_side_channel: Optional[
            DefaultTrainingAnalyticsSideChannel
        ] = None
        if DefaultTrainingAnalyticsSideChannel.CHANNEL_ID not in [
            _.channel_id for _ in side_channels
        ]:
            default_training_side_channel = DefaultTrainingAnalyticsSideChannel()
            side_channels.append(default_training_side_channel)
        self._side_channel_manager = SideChannelManager(side_channels)
        self._log_folder = log_folder
        self.academy_capabilities: UnityRLCapabilitiesProto = None  # type: ignore

        # If the environment name is None, a new environment will not be launched
        # and the communicator will directly try to connect to an existing unity environment.
        # If the worker-id is not 0 and the environment name is None, an error is thrown
        if file_name is None and worker_id != 0:
            raise UnityEnvironmentException(
                "If the environment name is None, "
                "the worker-id must be 0 in order to connect with the Editor."
            )
        if file_name is not None:
            try:
                self._process = env_utils.launch_executable(
                    file_name, self._executable_args()
                )
            except UnityEnvironmentException:
                self._close(0)
                raise
        else:
            logger.info(
                f"Listening on port {self._port}. "
                f"Start training by pressing the Play button in the Unity Editor."
            )
        self._loaded = True

View on GitHub (pinned to 3ecb446f75)

Solutions

Set worker_id=0 when file_name is None (connect to the Editor).
If you need multiple workers, pass a built environment binary as file_name along with distinct worker_ids.
Use no-graphics/base_port/worker_id combinations only with actual executables.

Example fix

// before
env = UnityEnvironment(file_name=None, worker_id=1)
# raises UnityEnvironmentException

// after
env = UnityEnvironment(file_name=None)  # worker_id defaults to 0 for Editor

Defensive patterns

Strategy: validation

Validate before calling

if file_name is None and worker_id != 0:
    worker_id = 0  # Editor connections require worker_id 0
env = UnityEnvironment(file_name=file_name, worker_id=worker_id)

Prevention

Only pass a nonzero worker_id when launching an actual executable via file_name.
Review copied training scripts for leftover worker_id arguments.
Document that worker_id offsets apply only to launched builds, not Editor connections.

When it happens

Trigger: UnityEnvironment(file_name=None, worker_id=N) with N != 0, typically while trying to connect to a Unity Editor instance; the constructor raises before any communicator setup.

Common situations: Scripting multi-worker training but testing against the Editor; copy-pasted worker_id arguments left in Editor-connect mode; assuming worker-id offsets apply to Editor connections.

Related errors

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