CoplayDev/unity-mcp · error · ConnectionError

Hash '{identifier}' matches multiple instances: {[inst.id fo

Error message

Hash '{identifier}' matches multiple instances: {[inst.id for inst in hash_matches]}

What it means

Raised by _resolve_instance_id (unity_connection.py:632) when the identifier is treated as a hash and its prefix matches more than one instance — the hash fragment is too short to be unique.

Source

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

                    "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)
            composite_matches = [
                inst for inst in instances
                if inst.name == name_part and (
                    inst.hash.startswith(hint_part) or str(
                        inst.port) == hint_part
                )
            ]
            if len(composite_matches) == 1:
                return composite_matches[0]

        # Try port match (as string)
        try:

View on GitHub (pinned to c21bf496bc)

Solutions

Provide a longer (or full) hash so it matches exactly one instance.
Use the Name@hash composite form instead of a bare hash.
Read mcpforunity://instances for exact identifiers.

Example fix

// before
unity_instance="a1"  # prefix matches several

// after
unity_instance="a1b2c3d4"  # enough chars to be unique

Defensive patterns

Strategy: validation

Validate before calling

instances = pool.discover_all_instances()

def hash_is_unique(prefix: str) -> bool:
    return sum(1 for i in instances if i.hash.startswith(prefix)) == 1

Type guard

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

Try / catch

try:
    await tool(ctx, unity_instance='a1b2')
except ConnectionError as e:
    if 'Hash' in str(e) and 'matches multiple instances' in str(e):
        await tool(ctx, unity_instance='a1b2c3d4e5f6')  # longer prefix
    else:
        raise

Prevention

Provide a long enough hash to be unique (or the full hash).
Use the Name@hash composite form instead of a bare hash prefix.
Resolve ids from mcpforunity://instances rather than typing hashes by hand.

When it happens

Trigger: Passing an abbreviated hash prefix (e.g. just the first few chars) that happens to be a prefix of two or more project hashes.

Common situations: User copies a truncated hash, or two projects share a long common hash prefix by coincidence.

Related errors

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