CoplayDev/unity-mcp · critical · ConnectionError

No Unity Editor instances found. Please ensure Unity is runn

Error message

No Unity Editor instances found. Please ensure Unity is running with MCP for Unity bridge.

What it means

Raised by _resolve_instance_id (unity_connection.py:573) when the discovered instances list is empty — PortDiscovery scanned for Unity editors with the MCPForUnity bridge registered and found none.

Source

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

            f"Found {len(instances)} Unity instances: {[inst.id for inst in instances]}")
        return instances

    def _resolve_instance_id(self, instance_identifier: str | None, instances: list[UnityInstanceInfo]) -> UnityInstanceInfo:
        """
        Resolve an instance identifier to a specific Unity instance.

        Args:
            instance_identifier: User-provided identifier (name, hash, name@hash, path, port, or None)
            instances: List of available instances

        Returns:
            Resolved UnityInstanceInfo

        Raises:
            ConnectionError: If instance cannot be resolved
        """
        if not instances:
            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(

View on GitHub (pinned to c21bf496bc)

Solutions

1. Open a Unity project that has the MCPForUnity package installed and enabled.
2. Confirm the bridge registered: look for ~/.unity-mcp/unity-mcp-status-*.json files.
3. Wait out the discovery TTL or force a refresh so a freshly-started editor is picked up.

from pathlib import Path

def any_unity_registered() -> bool:
    return bool(list(Path.home().joinpath('.unity-mcp').glob('unity-mcp-status-*.json')))

def is_no_instances(e: BaseException) -> bool:
    return (isinstance(e, ConnectionError)
            and 'No Unity Editor instances found' in str(e))

try:
    conn = pool.get_connection()
except ConnectionError as e:
    if 'No Unity Editor instances found' in str(e):
        # prompt the user to open Unity with MCPForUnity, then retry
        raise SystemExit('Open a Unity project with the MCPForUnity package enabled.')
    raise

When it happens

Trigger: Calling get_connection (directly or via any tool) when no Unity editor with the MCPForUnity package is running, or when the bridge has not yet written its status file to ~/.unity-mcp.

Common situations: Unity not opened, MCPForUnity package not installed/enabled in the project, the bridge never started, or discovery's cache (port_registry_ttl, default 5s) holding a stale empty result.

Related errors

• Could not connect to Unity
• Failed to connect to Unity instance '{target.id}' on port {t
• Multiple Unity instances are connected and none is selected.
• Project name '{identifier}' matches {len(name_matches)} inst
• Hash '{identifier}' matches multiple instances: {[inst.id fo

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