{"record":{"id":"2579bbd1a61750b3","repo":"CoplayDev/unity-mcp","slug":"multiple-unity-instances-are-connected-and-none-is","errorCode":null,"errorMessage":"Multiple Unity instances are connected and none is selected. Pass unity_instance on the call or use set_active_instance with one of: {available_ids}. Read mcpforunity://instances for current sessions.","messagePattern":"Multiple Unity instances are connected and none is selected\\. Pass unity_instance on the call or use set_active_instance with one of: (.+?)\\. Read mcpforunity://instances for current sessions\\.","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":591,"sourceCode":"            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(\n                    \"Multiple Unity instances are connected and none is selected. \"\n                    \"Pass unity_instance on the call or use set_active_instance \"\n                    f\"with one of: {available_ids}. \"\n                    \"Read mcpforunity://instances for current sessions.\"\n                )\n\n        identifier = instance_identifier.strip()\n\n        # Try exact ID match first\n        for inst in instances:\n            if inst.id == identifier:\n                return inst\n\n        # Try project name match\n        name_matches = [inst for inst in instances if inst.name == identifier]\n        if len(name_matches) == 1:\n            return name_matches[0]\n        elif len(name_matches) > 1:","sourceCodeStart":573,"sourceCodeEnd":609,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L573-L609","documentation":"Raised by _resolve_instance_id (unity_connection.py:591) when two or more Unity editors are registered, the caller supplied no unity_instance, and no default is pinned via set_active_instance. The library refuses to guess on purpose: silently routing to the most-recently-heartbeated editor could let one session retarget another project's Unity (#1023).","triggerScenarios":"Multiple Unity projects open simultaneously and calling a tool without a unity_instance argument and without a prior set_active_instance.","commonSituations":"Multi-project workflows, or a leftover editor from a previous session still registered in discovery.","solutions":["Pass unity_instance='Name@hash' explicitly on the call (ids are listed in the error).","Call set_active_instance once to pin a default.","Close the extra Unity editor(s) so only one remains."],"exampleFix":"// before\nresult = await manage_game_object(ctx, action=\"create\", name=\"Cube\")\n\n// after\nresult = await manage_game_object(\n    ctx, action=\"create\", name=\"Cube\", unity_instance=\"MyProject@a1b2c3\")","handlingStrategy":"validation","validationCode":"instances = pool.discover_all_instances()\n\ndef needs_explicit_instance() -> bool:\n    return len(instances) > 1 and pool._default_instance_id is None","typeGuard":"def is_instance_selection_required(e: BaseException) -> bool:\n    return (isinstance(e, ConnectionError)\n            and 'Multiple Unity instances are connected' in str(e))","tryCatchPattern":"try:\n    await tool(ctx, ...)\nexcept ConnectionError as e:\n    if 'Multiple Unity instances are connected' in str(e):\n        # parse the ids from the message or read the resource, then pin one\n        await set_active_instance(ctx, unity_instance='MyProject@a1b2c3')\n        await tool(ctx, ...)\n    else:\n        raise","preventionTips":["When running multiple Unity projects, always pass unity_instance or call set_active_instance first.","Close editors you are not actively using to keep discovery unambiguous.","Read mcpforunity://instances to obtain exact Name@hash ids."],"tags":["instance","selection","ambiguity","security","multi-project"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}