CoplayDev/unity-mcp · error · UnityConnectionError

Connection to Unity timed out after {cfg.timeout}s. Unity ma

Error message

Connection to Unity timed out after {cfg.timeout}s. Unity may be busy or unresponsive.

What it means

Raised by list_custom_tools() when the GET /api/custom-tools request does not complete within cfg.timeout seconds (the user-configurable timeout, unlike list_unity_instances which uses a hardcoded 10). The server accepted the TCP connection but did not finish responding in time. list_custom_tools relays to Unity to enumerate custom tools, so Unity-side latency is the usual root cause.

Source

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

    cfg = config or get_config()
    url = f"http://{cfg.host}:{cfg.port}/api/custom-tools"
    params: Dict[str, Any] = {}
    if cfg.unity_instance:
        params["instance"] = cfg.unity_instance

    try:
        async with httpx.AsyncClient() as client:
            response = await client.get(url, params=params, timeout=cfg.timeout)
            response.raise_for_status()
            return response.json()
    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(
            f"Connection to Unity timed out after {cfg.timeout}s. "
            f"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}")


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

View on GitHub (pinned to c21bf496bc)

Solutions

  1. Increase cfg.timeout via the CLI config (e.g., set timeout: 30) to allow more time for Unity to respond.
  2. Wait for Unity to finish compiling/importing and retry.
  3. If the project has a very large number of custom tools, consider reducing them or reporting the scan as slow to the package maintainers.
  4. Check for a wedged Unity Editor (not responding to pings) and restart it if necessary.

Example fix

// before — default timeout may be too short
response = await client.get(url, params=params, timeout=cfg.timeout)
// after — bump timeout in CLI config (cli config)
// config.yaml:
// timeout: 30
Defensive patterns

Strategy: retry

Validate before calling

# Ensure cfg.timeout is generous enough before calling list_custom_tools
from cli.utils.config import get_config
cfg = get_config()
if cfg.timeout < 10:
    print(f"Warning: cfg.timeout={cfg.timeout}s may be too low for custom-tools listing. Consider raising.")

Try / catch

from cli.utils.connection import UnityConnectionError
import time
for attempt in range(3):
    try:
        tools = run_list_custom_tools(config)
        break
    except UnityConnectionError as e:
        if "timed out" in str(e) and attempt < 2:
            time.sleep(5)
            continue
        raise

Prevention

When it happens

Trigger: Unity's main thread is blocked (compiling, importing, holding a modal dialog) so the server cannot get the custom-tool list back in time; the custom-tools endpoint does a slow reflection scan over a large assembly; cfg.timeout is set too low (e.g., 1-2 seconds) for a large project; network latency on a remote-hosted deployment.

Common situations: Default timeout too aggressive for large projects with many custom tools; Unity mid-recompile; remote-hosted mode with high-latency link between server and Unity; the server is processing a heavy batch_execute on the same Unity instance, starving this request.

Understand the failure class

Related errors

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