CoplayDev/unity-mcp · error · ValueError

No Unity instance found on port {value}. Available: {availab

Error message

No Unity instance found on port {value}. Available: {available}.

What it means

Raised in stdio mode when the caller passed a port number, the resolver enumerated discovered instances, and none reported that port. The error lists the available Name@hash ids and their ports so the caller can correct the value.

Source

Thrown at Server/src/transport/unity_instance_middleware.py:174

        transport = (config.transport_mode or "stdio").lower()

        # Port number (stdio only) — resolve to Name@hash via status file lookup
        if value.isdigit():
            if transport == "http":
                raise ValueError(
                    f"Port-based targeting ('{value}') is not supported in HTTP transport mode. "
                    "Use Name@hash or a hash prefix. Read mcpforunity://instances for available instances."
                )
            port_int = int(value)
            instances = await self._discover_instances(ctx)
            for inst in instances:
                if getattr(inst, "port", None) == port_int:
                    return inst.id
            available = ", ".join(
                f"{getattr(i, 'id', '?')} (port {getattr(i, 'port', '?')})"
                for i in instances
            ) or "none"
            raise ValueError(
                f"No Unity instance found on port {value}. Available: {available}."
            )

        instances = await self._discover_instances(ctx)
        ids = {
            getattr(inst, "id", None): inst
            for inst in instances
            if getattr(inst, "id", None)
        }

        # Exact Name@hash match
        if "@" in value:
            if value in ids:
                return value
            available = ", ".join(ids) or "none"
            raise ValueError(
                f"Instance '{value}' not found. Available: {available}. "
                "Read mcpforunity://instances for current sessions."

View on GitHub (pinned to c21bf496bc)

Solutions

1. Re-read the status file / mcpforunity://instances to get the current port mapping and use the matching Name@hash.
2. Prefer targeting by Name@hash or hash prefix, which is stable across port changes.
3. Confirm the intended Unity instance is actually running and connected.

Example fix

// before
await call_unity_tool('manage_gameobject', {...}, unity_instance='6401')
// after
await call_unity_tool('manage_gameobject', {...}, unity_instance='UnityMCPTests@a1b2c3d4')

instances = await middleware._discover_instances(ctx)
if value.isdigit() and int(value) not in {i.port for i in instances}:
    raise ValueError(f'Port {value} has no instance; available: {[(i.id,i.port) for i in instances]}')

def port_known(value: str, ports: set[int]) -> bool:
    return not value.isdigit() or int(value) in ports

try:
    await call_unity_tool(cmd, params, unity_instance=value)
except ValueError as e:
    if 'found on port' in str(e):
        instances = await read_resource('mcpforunity://instances')
        await call_unity_tool(cmd, params, unity_instance=instances[0]['id'])

When it happens

Trigger: value.isdigit() true, transport is stdio, _discover_instances returns instances whose .port attributes do not include the requested port_int. Falls through to the raise at unity_instance_middleware.py:178-180.

Common situations: The Unity plugin changed its bridge port (random/free-port assignment) but the client still uses the old port; the targeted instance was closed; another MCP server's plugin occupies a different port.

Related errors

• Port must be positive.
• Port {port} is already in use.
• unity_instance value must not be empty.
• Port-based targeting ('{value}') is not supported in HTTP tr
• Instance '{value}' not found. Available: {available}. Read m

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