CoplayDev/unity-mcp · error · ValueError

No running Unity instance matches '{value}'. Available: {ava

Error message

No running Unity instance matches '{value}'. Available: {available}. Read mcpforunity://instances for current sessions.

What it means

Raised when the supplied value is neither a port, nor an exact Name@hash, nor a unique hash prefix, and matches no running instance at all. This is the catch-all 'no such instance' terminal branch of resolve.

Source

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

                "Read mcpforunity://instances for current sessions."
            )

        # Hash prefix match
        lookup = value.lower()
        matches = [
            inst for inst in instances
            if getattr(inst, "hash", "") and getattr(inst, "hash", "").lower().startswith(lookup)
        ]
        if len(matches) == 1:
            return matches[0].id
        if len(matches) > 1:
            ambiguous = ", ".join(getattr(m, "id", "?") for m in matches)
            raise ValueError(
                f"Hash prefix '{value}' is ambiguous ({ambiguous}). "
                "Provide the full Name@hash from mcpforunity://instances."
            )
        available = ", ".join(ids) or "none"
        raise ValueError(
            f"No running Unity instance matches '{value}'. Available: {available}. "
            "Read mcpforunity://instances for current sessions."
        )

    async def _maybe_autoselect_instance(self, ctx) -> str | None:
        """
        Auto-select the sole Unity instance when no active instance is set.

        Note: This method both *discovers* and *persists* the selection via
        `set_active_instance` as a side-effect, since callers expect the selection
        to stick for subsequent tool/resource calls in the same session.
        """
        try:
            transport = (config.transport_mode or "stdio").lower()
            # This implicit behavior works well for solo-users, but is dangerous for multi-user setups
            if transport == "http" and config.http_remote_hosted:
                return None
            if PluginHub.is_configured():

View on GitHub (pinned to c21bf496bc)

Solutions

1. Read mcpforunity://instances and copy a valid Name@hash or hash prefix.
2. Confirm the intended Unity instance is connected.
3. If you intended auto-selection, omit unity_instance entirely instead of passing a guessed value.

Example fix

// before
await call_unity_tool('manage_gameobject', {...}, unity_instance='MyProject')  # no @hash
// after
await call_unity_tool('manage_gameobject', {...}, unity_instance='MyProject@a1b2c3d4')

ids = {getattr(i,'id',None) for i in instances}
hashes = [getattr(i,'hash','') for i in instances]
if value not in ids and not any(h.lower().startswith(value.lower()) for h in hashes):
    raise ValueError(f'{value!r} matches no instance')

def matches_some_instance(value: str, ids: set[str], hashes: list[str]) -> bool:
    v = value.lower()
    return value in ids or any(h.lower().startswith(v) for h in hashes)

try:
    await call_unity_tool(cmd, params, unity_instance=value)
except ValueError as e:
    if 'matches' 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 has no '@', is not all digits, and the hash-prefix match list is empty. The final raise at unity_instance_middleware.py:206-209 fires after listing available ids.

Common situations: Typo in the hash or instance name; the instance disconnected between read and call; wrong case (the lookup lowercases, but a fully wrong string still misses); passing a project name without '@hash'.

Related errors

• unity_instance value must not be empty.
• Port-based targeting ('{value}') is not supported in HTTP tr
• 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/0b67aae78f581c04. Report an issue: GitHub.