{"record":{"id":"b045822b2c853f95","repo":"CoplayDev/unity-mcp","slug":"hash-identifier-matches-multiple-instances","errorCode":null,"errorMessage":"Hash '{identifier}' matches multiple instances: {[inst.id for inst in hash_matches]}","messagePattern":"Hash '(.+?)' matches multiple instances: (.+?)","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":632,"sourceCode":"                    \"path\": inst.path,\n                    \"port\": inst.port,\n                    \"suggest\": f\"Use unity_instance='{inst.id}'\"\n                }\n                for inst in name_matches\n            ]\n            raise ConnectionError(\n                f\"Project name '{identifier}' matches {len(name_matches)} instances. \"\n                f\"Please use the full format (e.g., '{name_matches[0].id}'). \"\n                f\"Available instances: {suggestions}\"\n            )\n\n        # Try hash match\n        hash_matches = [inst for inst in instances if inst.hash ==\n                        identifier or inst.hash.startswith(identifier)]\n        if len(hash_matches) == 1:\n            return hash_matches[0]\n        elif len(hash_matches) > 1:\n            raise ConnectionError(\n                f\"Hash '{identifier}' matches multiple instances: {[inst.id for inst in hash_matches]}\"\n            )\n\n        # Try composite format: Name@Hash or Name@Port\n        if \"@\" in identifier:\n            name_part, hint_part = identifier.split(\"@\", 1)\n            composite_matches = [\n                inst for inst in instances\n                if inst.name == name_part and (\n                    inst.hash.startswith(hint_part) or str(\n                        inst.port) == hint_part\n                )\n            ]\n            if len(composite_matches) == 1:\n                return composite_matches[0]\n\n        # Try port match (as string)\n        try:","sourceCodeStart":614,"sourceCodeEnd":650,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L614-L650","documentation":"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.","triggerScenarios":"Passing an abbreviated hash prefix (e.g. just the first few chars) that happens to be a prefix of two or more project hashes.","commonSituations":"User copies a truncated hash, or two projects share a long common hash prefix by coincidence.","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."],"exampleFix":"// before\nunity_instance=\"a1\"  # prefix matches several\n\n// after\nunity_instance=\"a1b2c3d4\"  # enough chars to be unique","handlingStrategy":"validation","validationCode":"instances = pool.discover_all_instances()\n\ndef hash_is_unique(prefix: str) -> bool:\n    return sum(1 for i in instances if i.hash.startswith(prefix)) == 1","typeGuard":"def is_ambiguous_hash(e: BaseException) -> bool:\n    return (isinstance(e, ConnectionError)\n            and 'Hash' in str(e) and 'matches multiple instances' in str(e))","tryCatchPattern":"try:\n    await tool(ctx, unity_instance='a1b2')\nexcept ConnectionError as e:\n    if 'Hash' in str(e) and 'matches multiple instances' in str(e):\n        await tool(ctx, unity_instance='a1b2c3d4e5f6')  # longer prefix\n    else:\n        raise","preventionTips":["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."],"tags":["instance","hash","ambiguity","resolution"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}