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.

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

• Chunk size must be larger than 0
• Command parameters must be a dict for HTTP transport
• Could not find external project's validation results
• Could not load audio data
• Could not retrieve audio samples

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

Appendix: 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)