{"record":{"id":"10f6c600bde983d0","repo":"CoplayDev/unity-mcp","slug":"no-unity-editor-instances-found-please-ensure-uni","errorCode":null,"errorMessage":"No Unity Editor instances found. Please ensure Unity is running with MCP for Unity bridge.","messagePattern":"No Unity Editor instances found\\. Please ensure Unity is running with MCP for Unity bridge\\.","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"critical","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":573,"sourceCode":"            f\"Found {len(instances)} Unity instances: {[inst.id for inst in instances]}\")\n        return instances\n\n    def _resolve_instance_id(self, instance_identifier: str | None, instances: list[UnityInstanceInfo]) -> UnityInstanceInfo:\n        \"\"\"\n        Resolve an instance identifier to a specific Unity instance.\n\n        Args:\n            instance_identifier: User-provided identifier (name, hash, name@hash, path, port, or None)\n            instances: List of available instances\n\n        Returns:\n            Resolved UnityInstanceInfo\n\n        Raises:\n            ConnectionError: If instance cannot be resolved\n        \"\"\"\n        if not instances:\n            raise ConnectionError(\n                \"No Unity Editor instances found. Please ensure Unity is running with MCP for Unity bridge.\"\n            )\n\n        # Use default instance if no identifier provided\n        if instance_identifier is None:\n            if self._default_instance_id:\n                instance_identifier = self._default_instance_id\n                logger.debug(f\"Using default instance: {instance_identifier}\")\n            elif len(instances) == 1:\n                # Sole instance: unambiguous, select it without requiring a hint.\n                return instances[0]\n            else:\n                # 2+ instances connected and nothing pinned. Refuse to guess —\n                # silently routing to the most-recently-heartbeated editor lets\n                # an unbound session retarget another project's Unity (#1023).\n                # Mirror the HTTP \"multiple connected, no active set\" guard.\n                available_ids = [inst.id for inst in instances]\n                raise ConnectionError(","sourceCodeStart":555,"sourceCodeEnd":591,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L555-L591","documentation":"Raised by _resolve_instance_id (unity_connection.py:573) when the discovered instances list is empty — PortDiscovery scanned for Unity editors with the MCPForUnity bridge registered and found none.","triggerScenarios":"Calling get_connection (directly or via any tool) when no Unity editor with the MCPForUnity package is running, or when the bridge has not yet written its status file to ~/.unity-mcp.","commonSituations":"Unity not opened, MCPForUnity package not installed/enabled in the project, the bridge never started, or discovery's cache (port_registry_ttl, default 5s) holding a stale empty result.","solutions":["Open a Unity project that has the MCPForUnity package installed and enabled.","Confirm the bridge registered: look for ~/.unity-mcp/unity-mcp-status-*.json files.","Wait out the discovery TTL or force a refresh so a freshly-started editor is picked up."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef any_unity_registered() -> bool:\n    return bool(list(Path.home().joinpath('.unity-mcp').glob('unity-mcp-status-*.json')))","typeGuard":"def is_no_instances(e: BaseException) -> bool:\n    return (isinstance(e, ConnectionError)\n            and 'No Unity Editor instances found' in str(e))","tryCatchPattern":"try:\n    conn = pool.get_connection()\nexcept ConnectionError as e:\n    if 'No Unity Editor instances found' in str(e):\n        # prompt the user to open Unity with MCPForUnity, then retry\n        raise SystemExit('Open a Unity project with the MCPForUnity package enabled.')\n    raise","preventionTips":["Open a Unity project with MCPForUnity installed and enabled before invoking tools.","Confirm a ~/.unity-mcp/unity-mcp-status-*.json file exists once the bridge starts.","Allow discovery TTL (5s) to expire or force-refresh after starting Unity."],"tags":["discovery","instance","bridge","not-running"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}