CoplayDev/unity-mcp · error · NoUnitySessionError

No Unity plugins are currently connected

Error message

No Unity plugins are currently connected

What it means

Raised as NoUnitySessionError after the hub waited the full max_wait_s for a plugin WebSocket to register and none ever connected. It means the Unity side is not running the MCP for Unity plugin (or it was never installed/enabled), so there is no session to route to. This is the terminal 'Unity is not reachable' signal.

Source

Thrown at Server/src/transport/plugin_hub.py:985

                time.monotonic() - wait_started,
                unity_instance or "default",
            )
        if session_id is None and not target_hash and session_count > 1:
            raise InstanceSelectionRequiredError(
                InstanceSelectionRequiredError._MULTIPLE_INSTANCES)

        if session_id is None and explicit_required and not target_hash and session_count > 0:
            raise InstanceSelectionRequiredError()

        if session_id is None:
            logger.warning(
                "No Unity plugin reconnected within %.2fs (instance=%s)",
                max_wait_s,
                unity_instance or "default",
            )
            # At this point we've given the plugin ample time to reconnect; surface
            # a clear error so the client can prompt the user to open Unity.
            raise NoUnitySessionError(
                "No Unity plugins are currently connected")

        return session_id

    @classmethod
    async def send_command_for_instance(
        cls,
        unity_instance: str | None,
        command_type: str,
        params: dict[str, Any],
        user_id: str | None = None,
        retry_on_reload: bool = True,
    ) -> dict[str, Any]:
        """Send a command to a Unity instance.

        Args:
            unity_instance: Target instance (Name@hash or hash)
            command_type: Command type to execute

View on GitHub (pinned to c21bf496bc)

Solutions

1. Open (or reopen) the Unity project and confirm the MCP for Unity plugin shows a 'Connected' status.
2. Retry the tool call once Unity finishes compiling; transient domain reloads can exhaust the wait window.
3. If the issue persists, check the plugin Advanced Settings (host/port match the server) and the server log for inbound WebSocket handshakes at /hub/plugin.

Example fix

// before
result = await call_unity_tool('manage_gameobject', params)  # raises NoUnitySessionError
// after
try:
    result = await call_unity_tool('manage_gameobject', params)
except NoUnitySessionError:
    # prompt user to open Unity, then retry
    await asyncio.sleep(2)
    result = await call_unity_tool('manage_gameobject', params)

sessions = await hub.list_sessions()
if not sessions:
    raise RuntimeError('Unity is not connected; open the project first')

def unity_reachable(sessions: list) -> bool:
    return len(sessions) > 0

from transport.plugin_hub import NoUnitySessionError
for attempt in range(3):
    try:
        result = await call_unity_tool(cmd, params)
        break
    except NoUnitySessionError:
        if attempt == 2:
            raise
        await asyncio.sleep(2)

When it happens

Trigger: session_id stays None through the entire wait loop, session_count is 0 (or the single/selected target never reconnects), so the final guard at plugin_hub.py:977-986 fires. Typical of Unity closed, plugin window closed, or a domain reload that did not finish re-registering.

Common situations: Unity Editor was quit or crashed; the MCP for Unity package is installed but the plugin bridge was stopped from its Advanced Settings; a script-compilation domain reload took longer than max_wait_s; firewall/network split the plugin from the hub.

Related errors

• Invalid MCP base URL: {baseUrl}
• Export paths array cannot be empty
• Package Exporting failed: provided export paths are empty or
• Width should be larger than 0
• Height should be larger than 0

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