CoplayDev/unity-mcp · error · ValueError

Instance '{value}' not found. Available: {available}. Read m

Error message

Instance '{value}' not found. Available: {available}. Read mcpforunity://instances for current sessions.

What it means

Raised when the caller supplied a Name@hash string containing '@', but that exact id is not present among the currently running instances. The error enumerates the live ids so the caller can substitute a valid one.

Source

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

                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."
            )

        # 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."
            )

View on GitHub (pinned to c21bf496bc)

Solutions

1. Read mcpforunity://instances for the current Name@hash and use that value.
2. If the instance keeps changing hash, target by a unique hash prefix once it reappears.
3. Reopen the intended Unity project so its Name@hash re-registers.

Example fix

// before
await set_active_instance(ctx, name='MyProject@deadbeef')  # stale
// after
instances = await read_resource('mcpforunity://instances')
await set_active_instance(ctx, name=instances[0]['id'])  # e.g. MyProject@1a2b3c4d

instances = await middleware._discover_instances(ctx)
ids = {getattr(i, 'id', None) for i in instances}
if value and '@' in value and value not in ids:
    raise ValueError(f'{value} is not a live instance; refresh mcpforunity://instances')

def is_live_instance(value: str, live_ids: set[str]) -> bool:
    return '@' not in value or value in live_ids

try:
    await set_active_instance(ctx, name=value)
except ValueError as e:
    if 'not found' in str(e):
        instances = await read_resource('mcpforunity://instances')
        await set_active_instance(ctx, name=instances[0]['id'])

When it happens

Trigger: value contains '@' but value is not a key in the discovered ids dict. The guard at unity_instance_middleware.py:187-191 fires.

Common situations: The targeted Unity instance was closed and reopened (producing a different hash); the hash was mistyped or copy-pasted from a stale session; the instance is registered under a different project name.

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
• Hash prefix '{value}' is ambiguous ({ambiguous}). Provide th
• No running Unity instance matches '{value}'. Available: {ava

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