CoplayDev/unity-mcp · error · InstanceSelectionRequiredError

Unity instance selection is required. Call set_active_instan

Error message

Unity instance selection is required. Call set_active_instance with Name@hash from mcpforunity://instances.

What it means

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.

Source

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

            if explicit_required:
                return None, count, explicit_required
            if count == 1:
                return next(iter(sessions.keys())), count, explicit_required
            # Multiple sessions but no explicit target is ambiguous
            return None, count, explicit_required

        async def _available_instance_ids() -> list[str]:
            # Error path only; one extra registry read keeps the refusal actionable.
            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",

View on GitHub (pinned to c21bf496bc)

Solutions

1. Pass unity_instance='Name@hash' on the call (ids are in the error).
2. Call set_active_instance once to pin a default for the session.
3. Read the mcpforunity://instances resource to get a valid id.

Example fix

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

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

# In remote-hosted mode, always supply an instance
from core.config import config

def selection_satisfied(unity_instance: str | None) -> bool:
    return not config.http_remote_hosted or bool(unity_instance)

def is_instance_selection_required_http(e: BaseException) -> bool:
    return (isinstance(e, InstanceSelectionRequiredError)
            and 'selection is required' in str(e))

try:
    await tool(ctx, ...)
except InstanceSelectionRequiredError as e:
    # e.available_instances lists the valid Name@hash ids
    await set_active_instance(ctx, unity_instance=e.available_instances[0])
    await tool(ctx, ...)

When it happens

Trigger: A remote-hosted multi-tenant deployment where a tool call arrives without a unity_instance argument while at least one Unity plugin is connected.

Common situations: Hosted MCPForUnity server with multiple tenants/editors, or a client configured without a default instance.

Related errors

• Multiple Unity instances are connected. Call set_active_inst
• Multiple Unity instances are connected and none is selected.
• API key authentication required. Provide a valid X-API-Key h
• fal {phase} failed (status={res?.Status}): {detail}
• fal {phase} failed (status={res?.Status}): {detail}

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