CoplayDev/unity-mcp · error · ValueError

Hash prefix '{value}' is ambiguous ({ambiguous}). Provide th

Error message

Hash prefix '{value}' is ambiguous ({ambiguous}). Provide the full Name@hash from mcpforunity://instances.

What it means

Raised when the supplied value is treated as a hash prefix and that prefix matches more than one running instance, so the resolver cannot pick one deterministically. It lists the ambiguous candidate ids and asks for the full Name@hash.

Source

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

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

View on GitHub (pinned to c21bf496bc)

Solutions

1. Provide more hash characters, or the full Name@hash, to disambiguate.
2. Read mcpforunity://instances, copy the exact Name@hash of the intended instance, and pass that.
3. Close one of the colliding Unity instances so the prefix becomes unique.

Example fix

// before
await call_unity_tool('manage_gameobject', {...}, unity_instance='a1')  # ambiguous
// after
await call_unity_tool('manage_gameobject', {...}, unity_instance='a1b2c3d4')  # full hash

lookup = value.lower()
matches = [i for i in instances if getattr(i,'hash','').lower().startswith(lookup)]
if len(matches) > 1:
    raise ValueError(f'Ambiguous prefix; use full Name@hash: {[m.id for m in matches]}')

def is_unique_prefix(value: str, hashes: list[str]) -> bool:
    v = value.lower()
    return sum(1 for h in hashes if h.lower().startswith(v)) == 1

try:
    await call_unity_tool(cmd, params, unity_instance=value)
except ValueError as e:
    if 'ambiguous' in str(e):
        # lengthen to full hash from the message, then retry
        await call_unity_tool(cmd, params, unity_instance=full_hash)

When it happens

Trigger: value has no '@', value.lower() is a prefix of two or more instances' .hash fields. len(matches) > 1 at unity_instance_middleware.py:201 triggers the raise at 202-205.

Common situations: Two projects happened to share a hash prefix (only the first 8 hex chars are used); the user typed too few characters of the hash; multiple checkouts of the same project path registered near-identical hashes.

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
• No running Unity instance matches '{value}'. Available: {ava

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