CoplayDev/unity-mcp · error · ValueError

Port-based targeting ('{value}') is not supported in HTTP tr

Error message

Port-based targeting ('{value}') is not supported in HTTP transport mode. Use Name@hash or a hash prefix. Read mcpforunity://instances for available instances.

What it means

Raised by resolve when the user passed a bare port number (e.g. '6401') while the server is running in HTTP transport mode. Port-based targeting is a stdio-only convenience (it maps a port to a single local plugin via the status file); HTTP mode is multi-agent and requires a Name@hash or hash prefix instead.

Source

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

        Resolve a unity_instance string to a validated instance identifier.

        Accepts:
          - Bare port number like "6401" (stdio only) -> resolved Name@hash
          - "Name@hash" exact match
          - Hash prefix (unique prefix match against running instances)

        Raises ValueError with a user-friendly message on failure.
        """
        value = value.strip()
        if not value:
            raise ValueError("unity_instance value must not be empty.")

        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 = {

View on GitHub (pinned to c21bf496bc)

Solutions

1. Read mcpforunity://instances and pass a Name@hash (or unique hash prefix) instead of the port.
2. Switch the server back to stdio transport if per-port targeting is required.
3. Update any client config templates that hardcode a port so they read the instances resource.

Example fix

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

if config.transport_mode == 'http' and value and value.isdigit():
    raise ValueError('Use Name@hash in HTTP mode, not a port')

def is_http_safe_target(value: str, transport: str) -> bool:
    return not (transport == 'http' and value.isdigit())

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

When it happens

Trigger: config.transport_mode == 'http' and the unity_instance argument value.isdigit() is true. The guard at unity_instance_middleware.py:158-162 fires.

Common situations: Switched a deployment from stdio to HTTP transport but reused client configs that targeted by port; a tutorial/copy-paste carried over a stdio port value into an HTTP setup.

Related errors

• HTTP transport requires command arguments
• unity_instance value must not be empty.
• No Unity instance found on port {value}. Available: {availab
• Instance '{value}' not found. Available: {available}. Read m
• Hash prefix '{value}' is ambiguous ({ambiguous}). Provide th

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