{"record":{"id":"5e603fe891331b78","repo":"CoplayDev/unity-mcp","slug":"unity-instance-selection-is-required-call-set-act","errorCode":null,"errorMessage":"Unity instance selection is required. Call set_active_instance with Name@hash from mcpforunity://instances.","messagePattern":"Unity instance selection is required\\. 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":939,"sourceCode":"            if explicit_required:\n                return None, count, explicit_required\n            if count == 1:\n                return next(iter(sessions.keys())), count, explicit_required\n            # Multiple sessions but no explicit target is ambiguous\n            return None, count, explicit_required\n\n        async def _available_instance_ids() -> list[str]:\n            # Error path only; one extra registry read keeps the refusal actionable.\n            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\",","sourceCodeStart":921,"sourceCodeEnd":957,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/plugin_hub.py#L921-L957","documentation":"Raised by the HTTP transport session resolver (plugin_hub.py:939) in remote-hosted mode (config.http_remote_hosted=True). In that mode explicit selection is always required: with one or more plugin sessions present, no target hash, and no resolved session, it raises InstanceSelectionRequiredError carrying the available Name@hash ids.","triggerScenarios":"A remote-hosted multi-tenant deployment where a tool call arrives without a unity_instance argument while at least one Unity plugin is connected.","commonSituations":"Hosted MCPForUnity server with multiple tenants/editors, or a client configured without a default instance.","solutions":["Pass unity_instance='Name@hash' on the call (ids are in the error).","Call set_active_instance once to pin a default for the session.","Read the mcpforunity://instances resource to get a valid id."],"exampleFix":"// before\nawait manage_game_object(ctx, action=\"create\", name=\"Cube\")\n\n// after\nawait manage_game_object(\n    ctx, action=\"create\", name=\"Cube\", unity_instance=\"MyProject@a1b2c3\")","handlingStrategy":"validation","validationCode":"# In remote-hosted mode, always supply an instance\nfrom core.config import config\n\ndef selection_satisfied(unity_instance: str | None) -> bool:\n    return not config.http_remote_hosted or bool(unity_instance)","typeGuard":"def is_instance_selection_required_http(e: BaseException) -> bool:\n    return (isinstance(e, InstanceSelectionRequiredError)\n            and 'selection is required' in str(e))","tryCatchPattern":"try:\n    await tool(ctx, ...)\nexcept InstanceSelectionRequiredError as e:\n    # e.available_instances lists the valid Name@hash ids\n    await set_active_instance(ctx, unity_instance=e.available_instances[0])\n    await tool(ctx, ...)","preventionTips":["In remote-hosted deployments, always pass unity_instance or call set_active_instance first.","Use the available_instances attribute on the error rather than parsing the message.","Read mcpforunity://instances to obtain valid ids up front."],"tags":["http","instance","selection","remote-hosted","multi-tenant"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}