CoplayDev/unity-mcp · critical · ConnectionError

Failed to connect to Unity instance '{target.id}' on port {t

Error message

Failed to connect to Unity instance '{target.id}' on port {target.port}. Ensure the Unity Editor is running.

What it means

Raised by get_connection (unity_connection.py:699). The instance was resolved (so discovery succeeded), but opening the TCP socket to its port failed — connect() returned False. Discovery knew about the editor, but the live listener was unreachable.

Source

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

            UnityConnection to the specified instance

        Raises:
            ConnectionError: If instance cannot be found or connected
        """
        # Refresh instance list if cache expired
        instances = self.discover_all_instances()

        # Resolve identifier to specific instance
        target = self._resolve_instance_id(instance_identifier, instances)

        # Return existing connection or create new one
        with self._pool_lock:
            if target.id not in self._connections:
                logger.info(
                    f"Creating new connection to Unity instance: {target.id} (port {target.port})")
                conn = UnityConnection(port=target.port, instance_id=target.id)
                if not conn.connect():
                    raise ConnectionError(
                        f"Failed to connect to Unity instance '{target.id}' on port {target.port}. "
                        f"Ensure the Unity Editor is running."
                    )
                self._connections[target.id] = conn
            else:
                # Update existing connection with instance_id and port if changed
                conn = self._connections[target.id]
                conn.instance_id = target.id
                if conn.port != target.port:
                    logger.info(
                        f"Updating cached port for {target.id}: {conn.port} -> {target.port}")
                    conn.port = target.port
                logger.debug(f"Reusing existing connection to: {target.id}")

            return self._connections[target.id]

    def disconnect_all(self):
        """Disconnect all active connections"""

View on GitHub (pinned to c21bf496bc)

Solutions

1. Confirm the resolved editor is still open and the MCPForUnity bridge is active.
2. Force-refresh discovery so a stale entry is dropped or updated.
3. Restart the bridge (Unity Advanced Settings) and retry.

import socket

def instance_port_reachable(port: int) -> bool:
    try:
        with socket.create_connection((config.unity_host, port), 1.0):
            return True
    except OSError:
        return False

def is_instance_connect_failed(e: BaseException) -> bool:
    return (isinstance(e, ConnectionError)
            and 'Failed to connect to Unity instance' in str(e))

try:
    conn = pool.get_connection(unity_instance)
except ConnectionError as e:
    if 'Failed to connect to Unity instance' in str(e):
        # stale cache — force-refresh discovery and retry
        pool.discover_all_instances(force_refresh=True)
        conn = pool.get_connection(unity_instance)
    else:
        raise

When it happens

Trigger: An editor that registered a status file/port but whose bridge listener is not up — the editor closed after discovery cached it, the bridge crashed, or a firewall/port conflict blocks the connect.

Common situations: Editor closed after the discovery cache was populated, bridge process died, another process grabbed the port, or a host firewall.

Related errors

• Could not connect to Unity
• No Unity Editor instances found. Please ensure Unity is runn
• Port must be positive.
• Port {port} is already in use.
• No available ports found in range {DefaultPort}-{DefaultPort

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