{"record":{"id":"3e18245749eaee99","repo":"CoplayDev/unity-mcp","slug":"hash-prefix-value-is-ambiguous-ambiguous","errorCode":null,"errorMessage":"Hash prefix '{value}' is ambiguous ({ambiguous}). Provide the full Name@hash from mcpforunity://instances.","messagePattern":"Hash prefix '(.+?)' is ambiguous \\((.+?)\\)\\. Provide the full Name@hash from mcpforunity://instances\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/unity_instance_middleware.py","lineNumber":205,"sourceCode":"            if value in ids:\n                return value\n            available = \", \".join(ids) or \"none\"\n            raise ValueError(\n                f\"Instance '{value}' not found. Available: {available}. \"\n                \"Read mcpforunity://instances for current sessions.\"\n            )\n\n        # Hash prefix match\n        lookup = value.lower()\n        matches = [\n            inst for inst in instances\n            if getattr(inst, \"hash\", \"\") and getattr(inst, \"hash\", \"\").lower().startswith(lookup)\n        ]\n        if len(matches) == 1:\n            return matches[0].id\n        if len(matches) > 1:\n            ambiguous = \", \".join(getattr(m, \"id\", \"?\") for m in matches)\n            raise ValueError(\n                f\"Hash prefix '{value}' is ambiguous ({ambiguous}). \"\n                \"Provide the full Name@hash from mcpforunity://instances.\"\n            )\n        available = \", \".join(ids) or \"none\"\n        raise ValueError(\n            f\"No running Unity instance matches '{value}'. Available: {available}. \"\n            \"Read mcpforunity://instances for current sessions.\"\n        )\n\n    async def _maybe_autoselect_instance(self, ctx) -> str | None:\n        \"\"\"\n        Auto-select the sole Unity instance when no active instance is set.\n\n        Note: This method both *discovers* and *persists* the selection via\n        `set_active_instance` as a side-effect, since callers expect the selection\n        to stick for subsequent tool/resource calls in the same session.\n        \"\"\"\n        try:","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/unity_instance_middleware.py#L187-L223","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Provide more hash characters, or the full Name@hash, to disambiguate.","Read mcpforunity://instances, copy the exact Name@hash of the intended instance, and pass that.","Close one of the colliding Unity instances so the prefix becomes unique."],"exampleFix":"// before\nawait call_unity_tool('manage_gameobject', {...}, unity_instance='a1')  # ambiguous\n// after\nawait call_unity_tool('manage_gameobject', {...}, unity_instance='a1b2c3d4')  # full hash","handlingStrategy":"validation","validationCode":"lookup = value.lower()\nmatches = [i for i in instances if getattr(i,'hash','').lower().startswith(lookup)]\nif len(matches) > 1:\n    raise ValueError(f'Ambiguous prefix; use full Name@hash: {[m.id for m in matches]}')","typeGuard":"def is_unique_prefix(value: str, hashes: list[str]) -> bool:\n    v = value.lower()\n    return sum(1 for h in hashes if h.lower().startswith(v)) == 1","tryCatchPattern":"try:\n    await call_unity_tool(cmd, params, unity_instance=value)\nexcept ValueError as e:\n    if 'ambiguous' in str(e):\n        # lengthen to full hash from the message, then retry\n        await call_unity_tool(cmd, params, unity_instance=full_hash)","preventionTips":["Use the full 8-char hash or full Name@hash","Avoid short prefixes when many instances run","Close duplicate/colliding Unity projects"],"tags":["validation","unity-instance","ambiguous"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}