{"record":{"id":"23681d48866b11cf","repo":"CoplayDev/unity-mcp","slug":"failed-to-connect-to-unity-instance-target-id","errorCode":null,"errorMessage":"Failed to connect to Unity instance '{target.id}' on port {target.port}. Ensure the Unity Editor is running.","messagePattern":"Failed to connect to Unity instance '(.+?)' on port (.+?)\\. Ensure the Unity Editor is running\\.","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"critical","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":699,"sourceCode":"            UnityConnection to the specified instance\n\n        Raises:\n            ConnectionError: If instance cannot be found or connected\n        \"\"\"\n        # Refresh instance list if cache expired\n        instances = self.discover_all_instances()\n\n        # Resolve identifier to specific instance\n        target = self._resolve_instance_id(instance_identifier, instances)\n\n        # Return existing connection or create new one\n        with self._pool_lock:\n            if target.id not in self._connections:\n                logger.info(\n                    f\"Creating new connection to Unity instance: {target.id} (port {target.port})\")\n                conn = UnityConnection(port=target.port, instance_id=target.id)\n                if not conn.connect():\n                    raise ConnectionError(\n                        f\"Failed to connect to Unity instance '{target.id}' on port {target.port}. \"\n                        f\"Ensure the Unity Editor is running.\"\n                    )\n                self._connections[target.id] = conn\n            else:\n                # Update existing connection with instance_id and port if changed\n                conn = self._connections[target.id]\n                conn.instance_id = target.id\n                if conn.port != target.port:\n                    logger.info(\n                        f\"Updating cached port for {target.id}: {conn.port} -> {target.port}\")\n                    conn.port = target.port\n                logger.debug(f\"Reusing existing connection to: {target.id}\")\n\n            return self._connections[target.id]\n\n    def disconnect_all(self):\n        \"\"\"Disconnect all active connections\"\"\"","sourceCodeStart":681,"sourceCodeEnd":717,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L681-L717","documentation":"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.","triggerScenarios":"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.","commonSituations":"Editor closed after the discovery cache was populated, bridge process died, another process grabbed the port, or a host firewall.","solutions":["Confirm the resolved editor is still open and the MCPForUnity bridge is active.","Force-refresh discovery so a stale entry is dropped or updated.","Restart the bridge (Unity Advanced Settings) and retry."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"import socket\n\ndef instance_port_reachable(port: int) -> bool:\n    try:\n        with socket.create_connection((config.unity_host, port), 1.0):\n            return True\n    except OSError:\n        return False","typeGuard":"def is_instance_connect_failed(e: BaseException) -> bool:\n    return (isinstance(e, ConnectionError)\n            and 'Failed to connect to Unity instance' in str(e))","tryCatchPattern":"try:\n    conn = pool.get_connection(unity_instance)\nexcept ConnectionError as e:\n    if 'Failed to connect to Unity instance' in str(e):\n        # stale cache — force-refresh discovery and retry\n        pool.discover_all_instances(force_refresh=True)\n        conn = pool.get_connection(unity_instance)\n    else:\n        raise","preventionTips":["Force-refresh discovery after an editor restarts to drop stale entries.","Confirm the bridge is active in Unity Advanced Settings.","Retry get_connection once after a connect failure before surfacing to the user."],"tags":["connection","instance","port","bridge","stale-cache"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}