{"record":{"id":"6bee88176621c41a","repo":"CoplayDev/unity-mcp","slug":"unity-instance-identifier-not-found-available","errorCode":null,"errorMessage":"Unity instance '{identifier}' not found. Available instances: {available_ids}. Check mcpforunity://instances resource for all instances.","messagePattern":"Unity instance '(.+?)' not found\\. Available instances: (.+?)\\. Check mcpforunity://instances resource for all instances\\.","errorType":"exception","errorClass":"ConnectionError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/legacy/unity_connection.py","lineNumber":666,"sourceCode":"\n        # Try port match (as string)\n        try:\n            port_num = int(identifier)\n            port_matches = [\n                inst for inst in instances if inst.port == port_num]\n            if len(port_matches) == 1:\n                return port_matches[0]\n        except ValueError:\n            pass\n\n        # Try path match\n        path_matches = [inst for inst in instances if inst.path == identifier]\n        if len(path_matches) == 1:\n            return path_matches[0]\n\n        # Nothing matched\n        available_ids = [inst.id for inst in instances]\n        raise ConnectionError(\n            f\"Unity instance '{identifier}' not found. \"\n            f\"Available instances: {available_ids}. \"\n            f\"Check mcpforunity://instances resource for all instances.\"\n        )\n\n    def get_connection(self, instance_identifier: str | None = None) -> UnityConnection:\n        \"\"\"\n        Get or create a connection to a Unity instance.\n\n        Args:\n            instance_identifier: Optional identifier (name, hash, name@hash, etc.)\n                                If None, uses default or most recent instance\n\n        Returns:\n            UnityConnection to the specified instance\n\n        Raises:\n            ConnectionError: If instance cannot be found or connected","sourceCodeStart":648,"sourceCodeEnd":684,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/legacy/unity_connection.py#L648-L684","documentation":"Raised by _resolve_instance_id (unity_connection.py:666) after every resolution strategy (exact id, project name, hash, Name@Hash, port, path) failed to match the identifier. The error lists the available instance ids.","triggerScenarios":"Passing a stale id from a previous editor session, a typo, or an identifier for an editor that has since closed and dropped out of discovery.","commonSituations":"Cached/old instance id, editor restarted (new hash), or a mistyped identifier.","solutions":["Re-read the mcpforunity://instances resource for the current ids and use one of those.","Prefer the Name@hash form, which is stable across reconnects.","Ensure the target editor is still running and registered."],"exampleFix":"// before\nunity_instance=\"OldProject@deadbeef\"  # editor restarted, new hash\n\n// after\n# re-read mcpforunity://instances, then:\nunity_instance=\"OldProject@newhash1\"","handlingStrategy":"validation","validationCode":"instances = pool.discover_all_instances()\nvalid_ids = {i.id for i in instances}\n\ndef identifier_is_current(identifier: str) -> bool:\n    return identifier in valid_ids or any(\n        i.id == identifier or i.hash == identifier for i in instances)","typeGuard":"def is_instance_not_found(e: BaseException) -> bool:\n    return (isinstance(e, ConnectionError)\n            and 'not found' in str(e) and 'Available instances' in str(e))","tryCatchPattern":"try:\n    await tool(ctx, unity_instance=stale_id)\nexcept ConnectionError as e:\n    if 'not found' in str(e):\n        # re-read current instances and retry with a fresh id\n        current = await read_instances_resource(ctx)\n        await tool(ctx, unity_instance=current[0]['id'])\n    else:\n        raise","preventionTips":["Re-read mcpforunity://instances after an editor restarts — hashes change.","Prefer Name@hash, which is more stable than a bare port or path.","Don't cache instance ids across long-lived sessions without refreshing."],"tags":["instance","not-found","resolution","stale-id"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}