{"record":{"id":"64c46c5e71a7cd89","repo":"CoplayDev/unity-mcp","slug":"connection-to-unity-timed-out-after-timeout-or-cf","errorCode":null,"errorMessage":"Connection to Unity timed out after {timeout or 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":117,"sourceCode":"        payload[\"unity_instance\"] = cfg.unity_instance\n\n    try:\n        async with httpx.AsyncClient() as client:\n            response = await client.post(\n                url,\n                json=payload,\n                timeout=timeout or cfg.timeout,\n            )\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 {timeout or 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_command(\n    command_type: str,\n    params: Dict[str, Any],\n    config: Optional[CLIConfig] = None,\n    timeout: Optional[int] = None,\n) -> Dict[str, Any]:\n    \"\"\"Synchronous wrapper for send_command.","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/cli/utils/connection.py#L99-L135","documentation":"Thrown by send_command() when httpx raises a TimeoutException while posting to /api/command. It reports the effective timeout (the per-call override or cfg.timeout). Timeouts mean the server was reachable but did not respond in time — typically because Unity is busy compiling, importing, or hung.","triggerScenarios":"A command that triggers heavy Unity work (large asset import, script recompile, play-mode) exceeding the configured timeout, or an unresponsive Unity Editor. Reproducible with a low UNITY_MCP_TIMEOUT against a slow operation.","commonSituations":"Default 30s timeout too short for big texture/asset operations; Unity stuck on a modal dialog; or the Editor main thread blocked so the WebSocket→HTTP path stalls.","solutions":["Increase the timeout for heavy operations via the timeout argument or UNITY_MCP_TIMEOUT.","Ensure Unity is not blocked on a modal dialog or compilation during the call.","Split very large operations into smaller batches so each call completes within the timeout."],"exampleFix":"# before\nUNITY_MCP_TIMEOUT=10 unity-mcp texture create Assets/Big.png\n# after\nUNITY_MCP_TIMEOUT=120 unity-mcp texture create Assets/Big.png","handlingStrategy":"retry","validationCode":"import socket\n# pre-flight: confirm a response is plausible; size timeout to the operation\ntimeout = 120 if heavy_op else cfg.timeout","typeGuard":null,"tryCatchPattern":"for attempt in range(3):\n    try:\n        return await send_command(cmd, params, timeout=120)\n    except UnityConnectionError as e:\n        if \"timed out\" not in str(e) or attempt == 2:\n            raise","preventionTips":["Raise UNITY_MCP_TIMEOUT for heavy operations.","Ensure Unity is not blocked on a modal dialog."],"tags":["cli","network","timeout","http"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}