CoplayDev/unity-mcp · error · ConnectionError

Multiple Unity instances are connected and none is selected.

Error message

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.

What it means

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).

Source

Thrown at Server/src/transport/legacy/unity_connection.py:591

            raise ConnectionError(
                "No Unity Editor instances found. Please ensure Unity is running with MCP for Unity bridge."
            )

        # Use default instance if no identifier provided
        if instance_identifier is None:
            if self._default_instance_id:
                instance_identifier = self._default_instance_id
                logger.debug(f"Using default instance: {instance_identifier}")
            elif len(instances) == 1:
                # Sole instance: unambiguous, select it without requiring a hint.
                return instances[0]
            else:
                # 2+ instances connected and nothing pinned. Refuse to guess —
                # silently routing to the most-recently-heartbeated editor lets
                # an unbound session retarget another project's Unity (#1023).
                # Mirror the HTTP "multiple connected, no active set" guard.
                available_ids = [inst.id for inst in instances]
                raise ConnectionError(
                    "Multiple Unity instances are connected and none is selected. "
                    "Pass unity_instance on the call or use set_active_instance "
                    f"with one of: {available_ids}. "
                    "Read mcpforunity://instances for current sessions."
                )

        identifier = instance_identifier.strip()

        # Try exact ID match first
        for inst in instances:
            if inst.id == identifier:
                return inst

        # Try project name match
        name_matches = [inst for inst in instances if inst.name == identifier]
        if len(name_matches) == 1:
            return name_matches[0]
        elif len(name_matches) > 1:

View on GitHub (pinned to c21bf496bc)

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.

Example fix

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

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

Defensive patterns

Strategy: validation

Validate before calling

instances = pool.discover_all_instances()

def needs_explicit_instance() -> bool:
    return len(instances) > 1 and pool._default_instance_id is None

Type guard

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

Try / catch

try:
    await tool(ctx, ...)
except ConnectionError as e:
    if 'Multiple Unity instances are connected' in str(e):
        # parse the ids from the message or read the resource, then pin one
        await set_active_instance(ctx, unity_instance='MyProject@a1b2c3')
        await tool(ctx, ...)
    else:
        raise

Prevention

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.

When it happens

Trigger: Multiple Unity projects open simultaneously and calling a tool without a unity_instance argument and without a prior set_active_instance.

Common situations: Multi-project workflows, or a leftover editor from a previous session still registered in discovery.

Related errors

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