{"record":{"id":"dac50647cae4b14a","repo":"CoplayDev/unity-mcp","slug":"timeout-receiving-unity-response","errorCode":null,"errorMessage":"Timeout receiving Unity response","messagePattern":"Timeout receiving Unity response","errorType":"exception","errorClass":"TimeoutError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":206,"sourceCode":"                    if payload_len == 0:\n                        heartbeat_count += 1\n                        logger.debug(\n                            f\"Received heartbeat frame #{heartbeat_count}\")\n                        if heartbeat_count >= heartbeat_limit or (time.monotonic() - heartbeat_started) > heartbeat_window:\n                            raise TimeoutError(\n                                \"Unity sent heartbeat frames without payload within configured threshold\"\n                            )\n                        continue\n                    if payload_len > FRAMED_MAX:\n                        raise ValueError(\n                            f\"Invalid framed length: {payload_len}\")\n                    payload = self._read_exact(sock, payload_len)\n                    logger.debug(\n                        f\"Received framed response ({len(payload)} bytes)\")\n                    return payload\n            except socket.timeout as exc:\n                logger.warning(\"Socket timeout during framed receive\")\n                raise TimeoutError(\"Timeout receiving Unity response\") from exc\n            except TimeoutError:\n                raise\n            except Exception as exc:\n                logger.error(f\"Error during framed receive: {exc}\")\n                raise\n\n        chunks = []\n        # Respect the socket's currently configured timeout\n        try:\n            while True:\n                chunk = sock.recv(buffer_size)\n                if not chunk:\n                    if not chunks:\n                        raise Exception(\n                            \"Connection closed before receiving data\")\n                    break\n                chunks.append(chunk)\n","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L188-L224","documentation":"Raised in the framed receive loop (unity_connection.py:206): a socket.timeout while reading the header or payload is caught and re-raised as TimeoutError('Timeout receiving Unity response'). Unlike error 183 (too many heartbeats), this means the socket itself went silent — no bytes at all within the configured timeout.","triggerScenarios":"receive_full_response in framing mode where Unity stops sending entirely (frozen UI, hard deadlock, no heartbeats either), or a single recv exceeding connection_timeout / framed_receive_timeout.","commonSituations":"Unity editor frozen (spinning beachball / not responding), a network stall, or connection_timeout set too low for a legitimately heavy command.","solutions":["Raise UNITY_MCP_CONNECTION_TIMEOUT (and/or framed_receive_timeout) if the command legitimately needs longer.","Confirm Unity is responsive (not frozen on a dialog / infinite loop).","Rely on send_command retry to reconnect and re-attempt."],"exampleFix":"// before\n# UNITY_MCP_CONNECTION_TIMEOUT unset (300s) but framed recv stalls sooner\n\n// after\nexport UNITY_MCP_CONNECTION_TIMEOUT=600","handlingStrategy":"retry","validationCode":"import os\n\ndef framed_recv_timeout_adequate(estimated_seconds: float) -> bool:\n    return float(os.environ.get('UNITY_MCP_CONNECTION_TIMEOUT', 300)) >= estimated_seconds","typeGuard":"def is_framed_recv_timeout(e: BaseException) -> bool:\n    return (isinstance(e, TimeoutError)\n            and str(e) == 'Timeout receiving Unity response')","tryCatchPattern":"try:\n    resp = conn.send_command(cmd, params)\nexcept TimeoutError as e:\n    if str(e) == 'Timeout receiving Unity response':\n        conn.disconnect()  # clear possibly-stale socket\n        resp = conn.send_command(cmd, params)  # retry once\n    else:\n        raise","preventionTips":["Set UNITY_MCP_CONNECTION_TIMEOUT high enough for your heaviest command.","Confirm Unity is responsive (no frozen UI) before issuing long ops.","Let send_command retry rather than hand-rolling a single raw receive."],"tags":["timeout","framed","socket","unresponsive"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}