{"record":{"id":"c004099d24a23b73","repo":"CoplayDev/unity-mcp","slug":"command-command-type-exceeded-total-deadline-o","errorCode":null,"errorMessage":"Command '{command_type}' exceeded total deadline of {total_timeout:.1f}s (connection wedged or Unity unresponsive)","messagePattern":"Command '(.+?)' exceeded total deadline of (.+?)s \\(connection wedged or Unity unresponsive\\)","errorType":"exception","errorClass":"TimeoutError","httpStatus":null,"severity":"critical","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":359,"sourceCode":"            if status and (status.get('reloading') or status.get('reason') == 'reloading'):\n                # Reload invalidates the socket; drop it under the I/O lock so this\n                # close is serialized against the send/recv block, then reconnect next call.\n                with self._io_lock:\n                    self.disconnect()\n                return MCPResponse(\n                    success=False,\n                    error=\"Unity is reloading; please retry\",\n                    hint=\"retry\",\n                )\n        except Exception as exc:\n            logger.debug(f\"Preflight status check failed: {exc}\")\n\n        for attempt in range(attempts + 1):\n            if deadline is not None and time.monotonic() >= deadline:\n                logger.warning(\n                    \"Command '%s' exceeded total deadline of %.1fs after %d attempt(s); giving up\",\n                    command_type, total_timeout, attempt)\n                raise TimeoutError(\n                    f\"Command '{command_type}' exceeded total deadline of \"\n                    f\"{total_timeout:.1f}s (connection wedged or Unity unresponsive)\")\n            try:\n                # Discard stale sockets left over from a previous domain reload\n                # so we reconnect instead of writing to a dead connection.\n                self._ensure_live_connection()\n                # Ensure connected (handshake occurs within connect())\n                t_conn_start = time.time()\n                if not self.sock and not self.connect(self._cap_to_deadline(config.connection_timeout, deadline)):\n                    raise ConnectionError(\"Could not connect to Unity\")\n                logger.info(\"[TIMING-STDIO] connect took %.3fs command=%s\", time.time() - t_conn_start, command_type)\n\n                # Build payload\n                if command_type == 'ping':\n                    payload = b'ping'\n                else:\n                    payload = json.dumps({\n                        'type': command_type,","sourceCodeStart":341,"sourceCodeEnd":377,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L341-L377","documentation":"Raised by send_command (unity_connection.py:359). Beyond per-attempt timeouts, send_command enforces a hard total deadline across all retries (UNITY_MCP_COMMAND_TOTAL_TIMEOUT, default 600s). When time.monotonic() passes the deadline it gives up even if attempts remain, signaling a wedged socket or a Unity process that never responds.","triggerScenarios":"A command whose every attempt stalls (frozen editor, deadlock, repeated reconnect-then-timeout) so that cumulative wall-clock exceeds command_total_timeout before any attempt succeeds.","commonSituations":"Unity hard-frozen on an infinite loop, a deadlock, repeated domain reloads during the call, or network issues forcing reconnects that each burn part of the budget.","solutions":["Investigate why Unity is unresponsive — check the Editor console for errors, blocking dialogs, or a stuck PlayMode script.","If the operation legitimately needs longer, raise UNITY_MCP_COMMAND_TOTAL_TIMEOUT.","Restart the Unity editor and the MCPForUnity bridge to clear a wedged socket."],"exampleFix":"// before\n# default total deadline 600s; very long batch hits it\n\n// after\nexport UNITY_MCP_COMMAND_TOTAL_TIMEOUT=1800","handlingStrategy":"retry","validationCode":"import os\n\ndef total_deadline_adequate(estimated_seconds: float) -> bool:\n    return float(os.environ.get('UNITY_MCP_COMMAND_TOTAL_TIMEOUT', 600)) >= estimated_seconds","typeGuard":"def is_total_deadline_exceeded(e: BaseException) -> bool:\n    return (isinstance(e, TimeoutError)\n            and 'exceeded total deadline' in str(e))","tryCatchPattern":"try:\n    resp = conn.send_command(cmd, params)\nexcept TimeoutError as e:\n    if 'exceeded total deadline' in str(e):\n        # real wedge — restart bridge/editor, then retry with a fresh connection\n        conn.disconnect()\n        # surface to user / operator rather than silently looping\n        raise\n    raise","preventionTips":["Investigate editor freezes rather than only raising the deadline.","Set UNITY_MCP_COMMAND_TOTAL_TIMEOUT above your longest legitimate batch.","Restart the Unity bridge if a command repeatedly wedges."],"tags":["deadline","timeout","wedge","retry","unresponsive"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}