CoplayDev/unity-mcp · error · ConnectionError

Project name '{identifier}' matches {len(name_matches)} inst

Error message

Project name '{identifier}' matches {len(name_matches)} instances. Please use the full format (e.g., '{name_matches[0].id}'). Available instances: {suggestions}

What it means

Raised by _resolve_instance_id (unity_connection.py:620) when the identifier matched the project name of more than one instance — the name alone is ambiguous. The error embeds structured suggestions (id, path, port, and a 'Use unity_instance=...' hint) for each match.

Source

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

            if inst.id == identifier:
                return inst

        # Try project name match
        name_matches = [inst for inst in instances if inst.name == identifier]
        if len(name_matches) == 1:
            return name_matches[0]
        elif len(name_matches) > 1:
            # Multiple projects with same name - return helpful error
            suggestions = [
                {
                    "id": inst.id,
                    "path": inst.path,
                    "port": inst.port,
                    "suggest": f"Use unity_instance='{inst.id}'"
                }
                for inst in name_matches
            ]
            raise ConnectionError(
                f"Project name '{identifier}' matches {len(name_matches)} instances. "
                f"Please use the full format (e.g., '{name_matches[0].id}'). "
                f"Available instances: {suggestions}"
            )

        # Try hash match
        hash_matches = [inst for inst in instances if inst.hash ==
                        identifier or inst.hash.startswith(identifier)]
        if len(hash_matches) == 1:
            return hash_matches[0]
        elif len(hash_matches) > 1:
            raise ConnectionError(
                f"Hash '{identifier}' matches multiple instances: {[inst.id for inst in hash_matches]}"
            )

        # Try composite format: Name@Hash or Name@Port
        if "@" in identifier:
            name_part, hint_part = identifier.split("@", 1)

View on GitHub (pinned to c21bf496bc)

Solutions

Use the full Name@hash format taken from the suggestions in the error.
Close the duplicate editor so the name becomes unique.
Read the mcpforunity://instances resource to copy the exact id.

Example fix

// before
unity_instance="MyProject"  # ambiguous

// after
unity_instance="MyProject@a1b2c3"  # full id from suggestions

Defensive patterns

Strategy: validation

Validate before calling

instances = pool.discover_all_instances()

def name_is_unique(name: str) -> bool:
    return sum(1 for i in instances if i.name == name) == 1

Type guard

def is_ambiguous_name(e: BaseException) -> bool:
    return (isinstance(e, ConnectionError)
            and 'matches' in str(e) and 'instances' in str(e))

Try / catch

try:
    await tool(ctx, unity_instance='MyProject')
except ConnectionError as e:
    if 'matches' in str(e) and 'instances' in str(e):
        # use a full id instead of the bare name
        await tool(ctx, unity_instance='MyProject@a1b2c3')
    else:
        raise

Prevention

Prefer the full Name@hash id over a bare project name.
Close duplicate-named editors to remove ambiguity.
Pull exact ids from the mcpforunity://instances resource.

When it happens

Trigger: Two Unity projects with identical names open at once, or a stale registration of an editor that shares a name with a current one, and the caller passed only the project name.

Common situations: Duplicate/cloned project folders with the same name, or an old editor still registered alongside a new one.

Related errors

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