CoplayDev/unity-mcp · critical · TimeoutError

Command '{command_type}' exceeded total deadline of {total_t

Error message

Command '{command_type}' exceeded total deadline of {total_timeout:.1f}s (connection wedged or Unity unresponsive)

What it means

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.

Source

Thrown at Server/src/transport/legacy/unity_connection.py:359

            if status and (status.get('reloading') or status.get('reason') == 'reloading'):
                # Reload invalidates the socket; drop it under the I/O lock so this
                # close is serialized against the send/recv block, then reconnect next call.
                with self._io_lock:
                    self.disconnect()
                return MCPResponse(
                    success=False,
                    error="Unity is reloading; please retry",
                    hint="retry",
                )
        except Exception as exc:
            logger.debug(f"Preflight status check failed: {exc}")

        for attempt in range(attempts + 1):
            if deadline is not None and time.monotonic() >= deadline:
                logger.warning(
                    "Command '%s' exceeded total deadline of %.1fs after %d attempt(s); giving up",
                    command_type, total_timeout, attempt)
                raise TimeoutError(
                    f"Command '{command_type}' exceeded total deadline of "
                    f"{total_timeout:.1f}s (connection wedged or Unity unresponsive)")
            try:
                # Discard stale sockets left over from a previous domain reload
                # so we reconnect instead of writing to a dead connection.
                self._ensure_live_connection()
                # Ensure connected (handshake occurs within connect())
                t_conn_start = time.time()
                if not self.sock and not self.connect(self._cap_to_deadline(config.connection_timeout, deadline)):
                    raise ConnectionError("Could not connect to Unity")
                logger.info("[TIMING-STDIO] connect took %.3fs command=%s", time.time() - t_conn_start, command_type)

                # Build payload
                if command_type == 'ping':
                    payload = b'ping'
                else:
                    payload = json.dumps({
                        'type': command_type,

View on GitHub (pinned to c21bf496bc)

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.

Example fix

// before
# default total deadline 600s; very long batch hits it

// after
export UNITY_MCP_COMMAND_TOTAL_TIMEOUT=1800

Defensive patterns

Strategy: retry

Validate before calling

import os

def total_deadline_adequate(estimated_seconds: float) -> bool:
    return float(os.environ.get('UNITY_MCP_COMMAND_TOTAL_TIMEOUT', 600)) >= estimated_seconds

Type guard

def is_total_deadline_exceeded(e: BaseException) -> bool:
    return (isinstance(e, TimeoutError)
            and 'exceeded total deadline' in str(e))

Try / catch

try:
    resp = conn.send_command(cmd, params)
except TimeoutError as e:
    if 'exceeded total deadline' in str(e):
        # real wedge — restart bridge/editor, then retry with a fresh connection
        conn.disconnect()
        # surface to user / operator rather than silently looping
        raise
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/c004099d24a23b73. Report an issue: GitHub.