{"record":{"id":"37d406bac0a4e8a5","repo":"CoplayDev/unity-mcp","slug":"instance-value-not-found-available-availabl","errorCode":null,"errorMessage":"Instance '{value}' not found. Available: {available}. Read mcpforunity://instances for current sessions.","messagePattern":"Instance '(.+?)' not found\\. Available: (.+?)\\. Read mcpforunity://instances for current sessions\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/unity_instance_middleware.py","lineNumber":190,"sourceCode":"                for i in instances\n            ) or \"none\"\n            raise ValueError(\n                f\"No Unity instance found on port {value}. Available: {available}.\"\n            )\n\n        instances = await self._discover_instances(ctx)\n        ids = {\n            getattr(inst, \"id\", None): inst\n            for inst in instances\n            if getattr(inst, \"id\", None)\n        }\n\n        # Exact Name@hash match\n        if \"@\" in value:\n            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            )","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/unity_instance_middleware.py#L172-L208","documentation":"Raised when the caller supplied a Name@hash string containing '@', but that exact id is not present among the currently running instances. The error enumerates the live ids so the caller can substitute a valid one.","triggerScenarios":"value contains '@' but value is not a key in the discovered ids dict. The guard at unity_instance_middleware.py:187-191 fires.","commonSituations":"The targeted Unity instance was closed and reopened (producing a different hash); the hash was mistyped or copy-pasted from a stale session; the instance is registered under a different project name.","solutions":["Read mcpforunity://instances for the current Name@hash and use that value.","If the instance keeps changing hash, target by a unique hash prefix once it reappears.","Reopen the intended Unity project so its Name@hash re-registers."],"exampleFix":"// before\nawait set_active_instance(ctx, name='MyProject@deadbeef')  # stale\n// after\ninstances = await read_resource('mcpforunity://instances')\nawait set_active_instance(ctx, name=instances[0]['id'])  # e.g. MyProject@1a2b3c4d","handlingStrategy":"validation","validationCode":"instances = await middleware._discover_instances(ctx)\nids = {getattr(i, 'id', None) for i in instances}\nif value and '@' in value and value not in ids:\n    raise ValueError(f'{value} is not a live instance; refresh mcpforunity://instances')","typeGuard":"def is_live_instance(value: str, live_ids: set[str]) -> bool:\n    return '@' not in value or value in live_ids","tryCatchPattern":"try:\n    await set_active_instance(ctx, name=value)\nexcept ValueError as e:\n    if 'not found' in str(e):\n        instances = await read_resource('mcpforunity://instances')\n        await set_active_instance(ctx, name=instances[0]['id'])","preventionTips":["Re-read instances after Unity restarts (hash changes)","Copy Name@hash from the live instances resource, not a saved value","Treat stale-hash errors as a signal to refresh"],"tags":["validation","unity-instance","stale-session"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}