{"record":{"id":"6841474991e65651","repo":"Unity-Technologies/ml-agents","slug":"if-the-environment-name-is-none-the-worker-id-mus","errorCode":null,"errorMessage":"If the environment name is None, the worker-id must be 0 in order to connect with the Editor.","messagePattern":"If the environment name is None, the worker-id must be 0 in order to connect with the Editor\\.","errorType":"exception","errorClass":"UnityEnvironmentException","httpStatus":null,"severity":"error","filePath":"ml-agents-envs/mlagents_envs/environment.py","lineNumber":209,"sourceCode":"        if side_channels is None:\n            side_channels = []\n        default_training_side_channel: Optional[\n            DefaultTrainingAnalyticsSideChannel\n        ] = None\n        if DefaultTrainingAnalyticsSideChannel.CHANNEL_ID not in [\n            _.channel_id for _ in side_channels\n        ]:\n            default_training_side_channel = DefaultTrainingAnalyticsSideChannel()\n            side_channels.append(default_training_side_channel)\n        self._side_channel_manager = SideChannelManager(side_channels)\n        self._log_folder = log_folder\n        self.academy_capabilities: UnityRLCapabilitiesProto = None  # type: ignore\n\n        # If the environment name is None, a new environment will not be launched\n        # and the communicator will directly try to connect to an existing unity environment.\n        # If the worker-id is not 0 and the environment name is None, an error is thrown\n        if file_name is None and worker_id != 0:\n            raise UnityEnvironmentException(\n                \"If the environment name is None, \"\n                \"the worker-id must be 0 in order to connect with the Editor.\"\n            )\n        if file_name is not None:\n            try:\n                self._process = env_utils.launch_executable(\n                    file_name, self._executable_args()\n                )\n            except UnityEnvironmentException:\n                self._close(0)\n                raise\n        else:\n            logger.info(\n                f\"Listening on port {self._port}. \"\n                f\"Start training by pressing the Play button in the Unity Editor.\"\n            )\n        self._loaded = True\n","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/Unity-Technologies/ml-agents/blob/3ecb446f75d1e7400eb404c562dc005d3164cffc/ml-agents-envs/mlagents_envs/environment.py#L191-L227","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nenv = UnityEnvironment(file_name=None, worker_id=1)\n# raises UnityEnvironmentException\n\n// after\nenv = UnityEnvironment(file_name=None)  # worker_id defaults to 0 for Editor","handlingStrategy":"validation","validationCode":"if file_name is None and worker_id != 0:\n    worker_id = 0  # Editor connections require worker_id 0\nenv = UnityEnvironment(file_name=file_name, worker_id=worker_id)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["configuration","editor-connection","worker-id"],"backgroundTag":"invalid-constructor-argument","analyzedSha":"3ecb446f75d1e7400eb404c562dc005d3164cffc","analyzedAt":"2026-09-02T16:33:12.832Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}