{"record":{"id":"0b67aae78f581c04","repo":"CoplayDev/unity-mcp","slug":"no-running-unity-instance-matches-value-avail","errorCode":null,"errorMessage":"No running Unity instance matches '{value}'. Available: {available}. Read mcpforunity://instances for current sessions.","messagePattern":"No running Unity instance matches '(.+?)'\\. Available: (.+?)\\. Read mcpforunity://instances for current sessions\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/unity_instance_middleware.py","lineNumber":210,"sourceCode":"                \"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:\n            transport = (config.transport_mode or \"stdio\").lower()\n            # This implicit behavior works well for solo-users, but is dangerous for multi-user setups\n            if transport == \"http\" and config.http_remote_hosted:\n                return None\n            if PluginHub.is_configured():","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/unity_instance_middleware.py#L192-L228","documentation":"Raised when the supplied value is neither a port, nor an exact Name@hash, nor a unique hash prefix, and matches no running instance at all. This is the catch-all 'no such instance' terminal branch of resolve.","triggerScenarios":"value has no '@', is not all digits, and the hash-prefix match list is empty. The final raise at unity_instance_middleware.py:206-209 fires after listing available ids.","commonSituations":"Typo in the hash or instance name; the instance disconnected between read and call; wrong case (the lookup lowercases, but a fully wrong string still misses); passing a project name without '@hash'.","solutions":["Read mcpforunity://instances and copy a valid Name@hash or hash prefix.","Confirm the intended Unity instance is connected.","If you intended auto-selection, omit unity_instance entirely instead of passing a guessed value."],"exampleFix":"// before\nawait call_unity_tool('manage_gameobject', {...}, unity_instance='MyProject')  # no @hash\n// after\nawait call_unity_tool('manage_gameobject', {...}, unity_instance='MyProject@a1b2c3d4')","handlingStrategy":"validation","validationCode":"ids = {getattr(i,'id',None) for i in instances}\nhashes = [getattr(i,'hash','') for i in instances]\nif value not in ids and not any(h.lower().startswith(value.lower()) for h in hashes):\n    raise ValueError(f'{value!r} matches no instance')","typeGuard":"def matches_some_instance(value: str, ids: set[str], hashes: list[str]) -> bool:\n    v = value.lower()\n    return value in ids or any(h.lower().startswith(v) for h in hashes)","tryCatchPattern":"try:\n    await call_unity_tool(cmd, params, unity_instance=value)\nexcept ValueError as e:\n    if 'matches' in str(e):\n        instances = await read_resource('mcpforunity://instances')\n        await call_unity_tool(cmd, params, unity_instance=instances[0]['id'])","preventionTips":["Always include the '@' and full hash when known","Refresh the instances resource before targeting","Omit unity_instance to let auto-selection work"],"tags":["validation","unity-instance","not-found"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}