CoplayDev/unity-mcp · error · InstanceSelectionRequiredError

Multiple Unity instances are connected. Call set_active_inst

Error message

Multiple Unity instances are connected. Call set_active_instance with Name@hash from mcpforunity://instances.

What it means

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.

Source

Thrown at Server/src/transport/plugin_hub.py:948

            try:
                sessions = await cls._registry.list_sessions(user_id=user_id)
                return sorted(
                    f"{s.project_name}@{s.project_hash}" for s in sessions.values())
            except Exception:
                return []

        session_id, session_count, explicit_required = await _try_once()
        if session_id is None and explicit_required and not target_hash and session_count > 0:
            raise InstanceSelectionRequiredError(
                available_instances=await _available_instance_ids())
        deadline = time.monotonic() + max_wait_s
        wait_started = None

        # If there is no active plugin yet (e.g., Unity starting up or reloading),
        # wait politely for a session to appear before surfacing an error.
        while session_id is None and time.monotonic() < deadline:
            if not target_hash and session_count > 1:
                raise InstanceSelectionRequiredError(
                    InstanceSelectionRequiredError._MULTIPLE_INSTANCES,
                    available_instances=await _available_instance_ids())
            if session_id is None and explicit_required and not target_hash and session_count > 0:
                raise InstanceSelectionRequiredError(
                    available_instances=await _available_instance_ids())
            if wait_started is None:
                wait_started = time.monotonic()
                logger.debug(
                    "No plugin session available (instance=%s); waiting up to %.2fs",
                    unity_instance or "default",
                    max_wait_s,
                )
            await asyncio.sleep(sleep_seconds)
            session_id, session_count, explicit_required = await _try_once()

        if session_id is not None and wait_started is not None:
            logger.debug(
                "Plugin session restored after %.3fs (instance=%s)",

View on GitHub (pinned to c21bf496bc)

Solutions

1. Pass unity_instance='Name@hash' on the call.
2. Call set_active_instance to pin one editor.
3. Disconnect the extra Unity editor(s) so only one session remains.

Example fix

// before
await manage_game_object(ctx, action="create", name="Cube")

// after
await set_active_instance(ctx, unity_instance="MyProject@a1b2c3")
await manage_game_object(ctx, action="create", name="Cube")

# Resolve up front how many HTTP sessions exist
sessions = await PluginHub._registry.list_sessions()

def needs_explicit_http_instance() -> bool:
    return len(sessions) > 1

def is_multiple_http_instances(e: BaseException) -> bool:
    return (isinstance(e, InstanceSelectionRequiredError)
            and 'Multiple Unity instances are connected' in str(e))

try:
    await tool(ctx, ...)
except InstanceSelectionRequiredError as e:
    if 'Multiple Unity instances are connected' in str(e):
        await set_active_instance(ctx, unity_instance=e.available_instances[0])
        await tool(ctx, ...)
    else:
        raise

When it happens

Trigger: 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.

Common situations: Multi-project setup over the HTTP transport; an extra editor still connected from another workspace.

Related errors

• Multiple Unity instances are connected and none is selected.
• Unity instance selection is required. Call set_active_instan
• Project name '{identifier}' matches {len(name_matches)} inst
• Hash '{identifier}' matches multiple instances: {[inst.id fo
• fal {phase} failed (status={res?.Status}): {detail}

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/33c9ebd5ef5aac88. Report an issue: GitHub.