CoplayDev/unity-mcp · error · UnityConnectionError

Connection to Unity timed out while listing instances. Unity

Error message

Connection to Unity timed out while listing instances. Unity may be busy or unresponsive.

What it means

Raised by list_unity_instances() in the CLI connection layer when an HTTP GET to the MCP server's /api/instances endpoint does not complete within the hardcoded 10-second timeout. The CLI talks to the Python MCP server over HTTP (not to Unity directly); the server then relays to Unity. A TimeoutException means the server accepted the connection but never finished responding within 10s, usually because Unity itself is busy (importing assets, compiling, or stuck in a modal dialog).

Source

Thrown at Server/src/cli/utils/connection.py:201

    cfg = config or get_config()

    url = f"http://{cfg.host}:{cfg.port}/api/instances"

    try:
        async with httpx.AsyncClient() as client:
            response = await client.get(url, timeout=10)
            response.raise_for_status()
            data = response.json()
            if "instances" in data:
                return data
    except httpx.ConnectError as e:
        raise UnityConnectionError(
            f"Cannot connect to Unity MCP server at {cfg.host}:{cfg.port}. "
            f"Make sure the server is running and Unity is connected.\n"
            f"Error: {e}"
        )
    except httpx.TimeoutException:
        raise UnityConnectionError(
            "Connection to Unity timed out while listing instances. "
            "Unity may be busy or unresponsive."
        )
    except httpx.HTTPStatusError as e:
        raise UnityConnectionError(
            f"HTTP error from server: {e.response.status_code} - {e.response.text}"
        )
    except Exception as e:
        raise UnityConnectionError(f"Unexpected error: {e}")

    raise UnityConnectionError("Failed to list Unity instances")


def run_list_instances(config: Optional[CLIConfig] = None) -> Dict[str, Any]:
    """Synchronous wrapper for list_unity_instances."""
    return asyncio.run(list_unity_instances(config))

View on GitHub (pinned to c21bf496bc)

Solutions

Wait for Unity to finish its current operation (check for import/compile progress bars or modal dialogs) and retry the command.
Confirm the Python MCP server process is alive and not pinned at 100% CPU; restart it if it appears wedged.
Increase responsiveness by closing unnecessary Editor windows or pausing Play mode, which frees Unity's main thread.
If the 10s hard cap is too low for your workflow, patch list_unity_instances() to use cfg.timeout instead of the literal 10 (line 189).

Example fix

// before (Server/src/cli/utils/connection.py:189)
response = await client.get(url, timeout=10)
// after
response = await client.get(url, timeout=cfg.timeout)

Defensive patterns

Strategy: retry

Validate before calling

# Before calling list_unity_instances, check Unity responsiveness
import httpx
async def server_is_responsive(host: str, port: int, timeout: float = 2.0) -> bool:
    try:
        async with httpx.AsyncClient() as c:
            r = await c.get(f"http://{host}:{port}/api/health", timeout=timeout)
            return r.status_code == 200
    except Exception:
        return False

Try / catch

from cli.utils.connection import UnityConnectionError
try:
    instances = run_list_instances(config)
except UnityConnectionError as e:
    if "timed out" in str(e):
        # Unity may be busy; retry after a short wait or prompt user
        import time; time.sleep(5)
        instances = run_list_instances(config)
    else:
        raise

Prevention

Avoid calling list_instances while Unity is importing or compiling — wait for the Editor to be idle.
Monitor Unity Editor state via the editor_state resource before issuing CLI calls.
In automated scripts, wrap instance listing in a retry loop with exponential backoff for transient timeouts.

When it happens

Trigger: Run `unity-mcp instances` (or any code path calling run_list_instances/list_unity_instances) while Unity is performing a long asset import, domain reload, or compilation. Also triggered when the MCP server process is CPU-starved or the OS-level TCP stack stalls mid-transfer. The timeout is a fixed 10 seconds passed to httpx.AsyncClient.get — it is NOT the user-configurable cfg.timeout.

Common situations: Unity Editor is showing an import progress bar or 'Hold On' dialog; Unity is in the middle of a script recompile; the MCP server is shared by multiple AI clients (HTTP transport) and is saturated; a large project first-open causes Unity to block the main thread for >10s; firewall or VPN introduces latency on loopback.

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/2cb49513fd615070. Report an issue: GitHub.