{"record":{"id":"4b96fd57c4d067a1","repo":"CoplayDev/unity-mcp","slug":"project-name-identifier-matches-len-name-matc","errorCode":null,"errorMessage":"Project name '{identifier}' matches {len(name_matches)} instances. Please use the full format (e.g., '{name_matches[0].id}'). Available instances: {suggestions}","messagePattern":"Project name '(.+?)' matches (.+?) instances\\. Please use the full format \\(e\\.g\\., '(.+?)'\\)\\. Available instances: (.+?)","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":620,"sourceCode":"            if inst.id == identifier:\n                return inst\n\n        # Try project name match\n        name_matches = [inst for inst in instances if inst.name == identifier]\n        if len(name_matches) == 1:\n            return name_matches[0]\n        elif len(name_matches) > 1:\n            # Multiple projects with same name - return helpful error\n            suggestions = [\n                {\n                    \"id\": inst.id,\n                    \"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)","sourceCodeStart":602,"sourceCodeEnd":638,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L602-L638","documentation":"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.","triggerScenarios":"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.","commonSituations":"Duplicate/cloned project folders with the same name, or an old editor still registered alongside a new one.","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."],"exampleFix":"// before\nunity_instance=\"MyProject\"  # ambiguous\n\n// after\nunity_instance=\"MyProject@a1b2c3\"  # full id from suggestions","handlingStrategy":"validation","validationCode":"instances = pool.discover_all_instances()\n\ndef name_is_unique(name: str) -> bool:\n    return sum(1 for i in instances if i.name == name) == 1","typeGuard":"def is_ambiguous_name(e: BaseException) -> bool:\n    return (isinstance(e, ConnectionError)\n            and 'matches' in str(e) and 'instances' in str(e))","tryCatchPattern":"try:\n    await tool(ctx, unity_instance='MyProject')\nexcept ConnectionError as e:\n    if 'matches' in str(e) and 'instances' in str(e):\n        # use a full id instead of the bare name\n        await tool(ctx, unity_instance='MyProject@a1b2c3')\n    else:\n        raise","preventionTips":["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."],"tags":["instance","name","ambiguity","resolution"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}