{"record":{"id":"cc3622dfca8ab5c5","repo":"CoplayDev/unity-mcp","slug":"connection-to-unity-timed-out-after-cfg-timeout-s","errorCode":null,"errorMessage":"Connection to Unity timed out after {cfg.timeout}s. Unity may be busy or unresponsive.","messagePattern":"Connection to Unity timed out after (.+?)s\\. Unity may be busy or unresponsive\\.","errorType":"exception","errorClass":"UnityConnectionError","httpStatus":null,"severity":"error","filePath":"Server/src/cli/utils/connection.py","lineNumber":240,"sourceCode":"    cfg = config or get_config()\n    url = f\"http://{cfg.host}:{cfg.port}/api/custom-tools\"\n    params: Dict[str, Any] = {}\n    if cfg.unity_instance:\n        params[\"instance\"] = cfg.unity_instance\n\n    try:\n        async with httpx.AsyncClient() as client:\n            response = await client.get(url, params=params, timeout=cfg.timeout)\n            response.raise_for_status()\n            return response.json()\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            f\"Connection to Unity timed out after {cfg.timeout}s. \"\n            f\"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\ndef run_list_custom_tools(config: Optional[CLIConfig] = None) -> Dict[str, Any]:\n    \"\"\"Synchronous wrapper for list_custom_tools.\"\"\"\n    return asyncio.run(list_custom_tools(config))\n","sourceCodeStart":222,"sourceCodeEnd":255,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/cli/utils/connection.py#L222-L255","documentation":"Raised by list_custom_tools() when the GET /api/custom-tools request does not complete within cfg.timeout seconds (the user-configurable timeout, unlike list_unity_instances which uses a hardcoded 10). The server accepted the TCP connection but did not finish responding in time. list_custom_tools relays to Unity to enumerate custom tools, so Unity-side latency is the usual root cause.","triggerScenarios":"Unity's main thread is blocked (compiling, importing, holding a modal dialog) so the server cannot get the custom-tool list back in time; the custom-tools endpoint does a slow reflection scan over a large assembly; cfg.timeout is set too low (e.g., 1-2 seconds) for a large project; network latency on a remote-hosted deployment.","commonSituations":"Default timeout too aggressive for large projects with many custom tools; Unity mid-recompile; remote-hosted mode with high-latency link between server and Unity; the server is processing a heavy batch_execute on the same Unity instance, starving this request.","solutions":["Increase cfg.timeout via the CLI config (e.g., set timeout: 30) to allow more time for Unity to respond.","Wait for Unity to finish compiling/importing and retry.","If the project has a very large number of custom tools, consider reducing them or reporting the scan as slow to the package maintainers.","Check for a wedged Unity Editor (not responding to pings) and restart it if necessary."],"exampleFix":"// before — default timeout may be too short\nresponse = await client.get(url, params=params, timeout=cfg.timeout)\n// after — bump timeout in CLI config (cli config)\n// config.yaml:\n// timeout: 30","handlingStrategy":"retry","validationCode":"# Ensure cfg.timeout is generous enough before calling list_custom_tools\nfrom cli.utils.config import get_config\ncfg = get_config()\nif cfg.timeout < 10:\n    print(f\"Warning: cfg.timeout={cfg.timeout}s may be too low for custom-tools listing. Consider raising.\")","typeGuard":null,"tryCatchPattern":"from cli.utils.connection import UnityConnectionError\nimport time\nfor attempt in range(3):\n    try:\n        tools = run_list_custom_tools(config)\n        break\n    except UnityConnectionError as e:\n        if \"timed out\" in str(e) and attempt < 2:\n            time.sleep(5)\n            continue\n        raise","preventionTips":["Set cfg.timeout to at least 15-30 seconds for projects with many custom tools.","Avoid listing custom tools during Unity compile/import operations.","Use retry-with-backoff in automated scripts for transient Unity busy states."],"tags":["network","timeout","cli","httpx","configurable-timeout"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}