{"record":{"id":"2cb49513fd615070","repo":"CoplayDev/unity-mcp","slug":"connection-to-unity-timed-out-while-listing-instan","errorCode":null,"errorMessage":"Connection to Unity timed out while listing instances. Unity may be busy or unresponsive.","messagePattern":"Connection to Unity timed out while listing instances\\. Unity may be busy or unresponsive\\.","errorType":"exception","errorClass":"UnityConnectionError","httpStatus":null,"severity":"error","filePath":"Server/src/cli/utils/connection.py","lineNumber":201,"sourceCode":"    cfg = config or get_config()\n\n    url = f\"http://{cfg.host}:{cfg.port}/api/instances\"\n\n    try:\n        async with httpx.AsyncClient() as client:\n            response = await client.get(url, timeout=10)\n            response.raise_for_status()\n            data = response.json()\n            if \"instances\" in data:\n                return data\n    except httpx.ConnectError as e:\n        raise UnityConnectionError(\n            f\"Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}. \"\n            f\"Make sure the server is running and Unity is connected.\\n\"\n            f\"Error: {e}\"\n        )\n    except httpx.TimeoutException:\n        raise UnityConnectionError(\n            \"Connection to Unity timed out while listing instances. \"\n            \"Unity may be busy or unresponsive.\"\n        )\n    except httpx.HTTPStatusError as e:\n        raise UnityConnectionError(\n            f\"HTTP error from server: {e.response.status_code} - {e.response.text}\"\n        )\n    except Exception as e:\n        raise UnityConnectionError(f\"Unexpected error: {e}\")\n\n    raise UnityConnectionError(\"Failed to list Unity instances\")\n\n\ndef run_list_instances(config: Optional[CLIConfig] = None) -> Dict[str, Any]:\n    \"\"\"Synchronous wrapper for list_unity_instances.\"\"\"\n    return asyncio.run(list_unity_instances(config))\n\n","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/cli/utils/connection.py#L183-L219","documentation":"Raised by list_unity_instances() in the CLI connection layer when an HTTP GET to the MCP server's /api/instances endpoint does not complete within the hardcoded 10-second timeout. The CLI talks to the Python MCP server over HTTP (not to Unity directly); the server then relays to Unity. A TimeoutException means the server accepted the connection but never finished responding within 10s, usually because Unity itself is busy (importing assets, compiling, or stuck in a modal dialog).","triggerScenarios":"Run `unity-mcp instances` (or any code path calling run_list_instances/list_unity_instances) while Unity is performing a long asset import, domain reload, or compilation. Also triggered when the MCP server process is CPU-starved or the OS-level TCP stack stalls mid-transfer. The timeout is a fixed 10 seconds passed to httpx.AsyncClient.get — it is NOT the user-configurable cfg.timeout.","commonSituations":"Unity Editor is showing an import progress bar or 'Hold On' dialog; Unity is in the middle of a script recompile; the MCP server is shared by multiple AI clients (HTTP transport) and is saturated; a large project first-open causes Unity to block the main thread for >10s; firewall or VPN introduces latency on loopback.","solutions":["Wait for Unity to finish its current operation (check for import/compile progress bars or modal dialogs) and retry the command.","Confirm the Python MCP server process is alive and not pinned at 100% CPU; restart it if it appears wedged.","Increase responsiveness by closing unnecessary Editor windows or pausing Play mode, which frees Unity's main thread.","If the 10s hard cap is too low for your workflow, patch list_unity_instances() to use cfg.timeout instead of the literal 10 (line 189)."],"exampleFix":"// before (Server/src/cli/utils/connection.py:189)\nresponse = await client.get(url, timeout=10)\n// after\nresponse = await client.get(url, timeout=cfg.timeout)","handlingStrategy":"retry","validationCode":"# Before calling list_unity_instances, check Unity responsiveness\nimport httpx\nasync def server_is_responsive(host: str, port: int, timeout: float = 2.0) -> bool:\n    try:\n        async with httpx.AsyncClient() as c:\n            r = await c.get(f\"http://{host}:{port}/api/health\", timeout=timeout)\n            return r.status_code == 200\n    except Exception:\n        return False","typeGuard":null,"tryCatchPattern":"from cli.utils.connection import UnityConnectionError\ntry:\n    instances = run_list_instances(config)\nexcept UnityConnectionError as e:\n    if \"timed out\" in str(e):\n        # Unity may be busy; retry after a short wait or prompt user\n        import time; time.sleep(5)\n        instances = run_list_instances(config)\n    else:\n        raise","preventionTips":["Avoid calling list_instances while Unity is importing or compiling — wait for the Editor to be idle.","Monitor Unity Editor state via the editor_state resource before issuing CLI calls.","In automated scripts, wrap instance listing in a retry loop with exponential backoff for transient timeouts."],"tags":["network","timeout","cli","httpx","unity-busy"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}