{"record":{"id":"33c9ebd5ef5aac88","repo":"CoplayDev/unity-mcp","slug":"multiple-unity-instances-are-connected-call-set-a","errorCode":null,"errorMessage":"Multiple Unity instances are connected. Call set_active_instance with Name@hash from mcpforunity://instances.","messagePattern":"Multiple Unity instances are connected\\. Call set_active_instance with Name@hash from mcpforunity://instances\\.","errorType":"exception","errorClass":"InstanceSelectionRequiredError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/plugin_hub.py","lineNumber":948,"sourceCode":"            try:\n                sessions = await cls._registry.list_sessions(user_id=user_id)\n                return sorted(\n                    f\"{s.project_name}@{s.project_hash}\" for s in sessions.values())\n            except Exception:\n                return []\n\n        session_id, session_count, explicit_required = await _try_once()\n        if session_id is None and explicit_required and not target_hash and session_count > 0:\n            raise InstanceSelectionRequiredError(\n                available_instances=await _available_instance_ids())\n        deadline = time.monotonic() + max_wait_s\n        wait_started = None\n\n        # If there is no active plugin yet (e.g., Unity starting up or reloading),\n        # wait politely for a session to appear before surfacing an error.\n        while session_id is None and time.monotonic() < deadline:\n            if not target_hash and session_count > 1:\n                raise InstanceSelectionRequiredError(\n                    InstanceSelectionRequiredError._MULTIPLE_INSTANCES,\n                    available_instances=await _available_instance_ids())\n            if session_id is None and explicit_required and not target_hash and session_count > 0:\n                raise InstanceSelectionRequiredError(\n                    available_instances=await _available_instance_ids())\n            if wait_started is None:\n                wait_started = time.monotonic()\n                logger.debug(\n                    \"No plugin session available (instance=%s); waiting up to %.2fs\",\n                    unity_instance or \"default\",\n                    max_wait_s,\n                )\n            await asyncio.sleep(sleep_seconds)\n            session_id, session_count, explicit_required = await _try_once()\n\n        if session_id is not None and wait_started is not None:\n            logger.debug(\n                \"Plugin session restored after %.3fs (instance=%s)\",","sourceCodeStart":930,"sourceCodeEnd":966,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/plugin_hub.py#L930-L966","documentation":"Raised by the HTTP transport session resolver inside its wait loop (plugin_hub.py:948). When there is no target hash and more than one plugin session exists, the library refuses to auto-pick one — the HTTP mirror of the stdio guard (#1023) to avoid silently retargeting another project's editor.","triggerScenarios":"Two or more Unity editors connected over /hub/plugin WebSockets and a tool call arrives without a unity_instance and without a pinned active instance.","commonSituations":"Multi-project setup over the HTTP transport; an extra editor still connected from another workspace.","solutions":["Pass unity_instance='Name@hash' on the call.","Call set_active_instance to pin one editor.","Disconnect the extra Unity editor(s) so only one session remains."],"exampleFix":"// before\nawait manage_game_object(ctx, action=\"create\", name=\"Cube\")\n\n// after\nawait set_active_instance(ctx, unity_instance=\"MyProject@a1b2c3\")\nawait manage_game_object(ctx, action=\"create\", name=\"Cube\")","handlingStrategy":"validation","validationCode":"# Resolve up front how many HTTP sessions exist\nsessions = await PluginHub._registry.list_sessions()\n\ndef needs_explicit_http_instance() -> bool:\n    return len(sessions) > 1","typeGuard":"def is_multiple_http_instances(e: BaseException) -> bool:\n    return (isinstance(e, InstanceSelectionRequiredError)\n            and 'Multiple Unity instances are connected' in str(e))","tryCatchPattern":"try:\n    await tool(ctx, ...)\nexcept InstanceSelectionRequiredError as e:\n    if 'Multiple Unity instances are connected' in str(e):\n        await set_active_instance(ctx, unity_instance=e.available_instances[0])\n        await tool(ctx, ...)\n    else:\n        raise","preventionTips":["Pin an active instance with set_active_instance in multi-editor HTTP setups.","Disconnect Unity editors you are not actively driving.","Read mcpforunity://instances to enumerate connected sessions."],"tags":["http","instance","ambiguity","selection","multi-project"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}