CoplayDev/unity-mcp · error · ConnectionError

Unity instance '{identifier}' not found. Available instances

Error message

Unity instance '{identifier}' not found. Available instances: {available_ids}. Check mcpforunity://instances resource for all instances.

What it means

Raised by _resolve_instance_id (unity_connection.py:666) after every resolution strategy (exact id, project name, hash, Name@Hash, port, path) failed to match the identifier. The error lists the available instance ids.

Source

Thrown at Server/src/transport/legacy/unity_connection.py:666

        # Try port match (as string)
        try:
            port_num = int(identifier)
            port_matches = [
                inst for inst in instances if inst.port == port_num]
            if len(port_matches) == 1:
                return port_matches[0]
        except ValueError:
            pass

        # Try path match
        path_matches = [inst for inst in instances if inst.path == identifier]
        if len(path_matches) == 1:
            return path_matches[0]

        # Nothing matched
        available_ids = [inst.id for inst in instances]
        raise ConnectionError(
            f"Unity instance '{identifier}' not found. "
            f"Available instances: {available_ids}. "
            f"Check mcpforunity://instances resource for all instances."
        )

    def get_connection(self, instance_identifier: str | None = None) -> UnityConnection:
        """
        Get or create a connection to a Unity instance.

        Args:
            instance_identifier: Optional identifier (name, hash, name@hash, etc.)
                                If None, uses default or most recent instance

        Returns:
            UnityConnection to the specified instance

        Raises:
            ConnectionError: If instance cannot be found or connected

View on GitHub (pinned to c21bf496bc)

Solutions

Re-read the mcpforunity://instances resource for the current ids and use one of those.
Prefer the Name@hash form, which is stable across reconnects.
Ensure the target editor is still running and registered.

Example fix

// before
unity_instance="OldProject@deadbeef"  # editor restarted, new hash

// after
# re-read mcpforunity://instances, then:
unity_instance="OldProject@newhash1"

Defensive patterns

Strategy: validation

Validate before calling

instances = pool.discover_all_instances()
valid_ids = {i.id for i in instances}

def identifier_is_current(identifier: str) -> bool:
    return identifier in valid_ids or any(
        i.id == identifier or i.hash == identifier for i in instances)

Type guard

def is_instance_not_found(e: BaseException) -> bool:
    return (isinstance(e, ConnectionError)
            and 'not found' in str(e) and 'Available instances' in str(e))

Try / catch

try:
    await tool(ctx, unity_instance=stale_id)
except ConnectionError as e:
    if 'not found' in str(e):
        # re-read current instances and retry with a fresh id
        current = await read_instances_resource(ctx)
        await tool(ctx, unity_instance=current[0]['id'])
    else:
        raise

Prevention

Re-read mcpforunity://instances after an editor restarts — hashes change.
Prefer Name@hash, which is more stable than a bare port or path.
Don't cache instance ids across long-lived sessions without refreshing.

When it happens

Trigger: Passing a stale id from a previous editor session, a typo, or an identifier for an editor that has since closed and dropped out of discovery.

Common situations: Cached/old instance id, editor restarted (new hash), or a mistyped identifier.

Related errors

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