{"record":{"id":"967c89f3f3d385ad","repo":"CoplayDev/unity-mcp","slug":"no-unity-instance-found-on-port-value-available","errorCode":null,"errorMessage":"No Unity instance found on port {value}. Available: {available}.","messagePattern":"No Unity instance found on port (.+?)\\. Available: (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/unity_instance_middleware.py","lineNumber":174,"sourceCode":"        transport = (config.transport_mode or \"stdio\").lower()\n\n        # Port number (stdio only) — resolve to Name@hash via status file lookup\n        if value.isdigit():\n            if transport == \"http\":\n                raise ValueError(\n                    f\"Port-based targeting ('{value}') is not supported in HTTP transport mode. \"\n                    \"Use Name@hash or a hash prefix. Read mcpforunity://instances for available instances.\"\n                )\n            port_int = int(value)\n            instances = await self._discover_instances(ctx)\n            for inst in instances:\n                if getattr(inst, \"port\", None) == port_int:\n                    return inst.id\n            available = \", \".join(\n                f\"{getattr(i, 'id', '?')} (port {getattr(i, 'port', '?')})\"\n                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.\"","sourceCodeStart":156,"sourceCodeEnd":192,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/unity_instance_middleware.py#L156-L192","documentation":"Raised in stdio mode when the caller passed a port number, the resolver enumerated discovered instances, and none reported that port. The error lists the available Name@hash ids and their ports so the caller can correct the value.","triggerScenarios":"value.isdigit() true, transport is stdio, _discover_instances returns instances whose .port attributes do not include the requested port_int. Falls through to the raise at unity_instance_middleware.py:178-180.","commonSituations":"The Unity plugin changed its bridge port (random/free-port assignment) but the client still uses the old port; the targeted instance was closed; another MCP server's plugin occupies a different port.","solutions":["Re-read the status file / mcpforunity://instances to get the current port mapping and use the matching Name@hash.","Prefer targeting by Name@hash or hash prefix, which is stable across port changes.","Confirm the intended Unity instance is actually running and connected."],"exampleFix":"// before\nawait call_unity_tool('manage_gameobject', {...}, unity_instance='6401')\n// after\nawait call_unity_tool('manage_gameobject', {...}, unity_instance='UnityMCPTests@a1b2c3d4')","handlingStrategy":"validation","validationCode":"instances = await middleware._discover_instances(ctx)\nif value.isdigit() and int(value) not in {i.port for i in instances}:\n    raise ValueError(f'Port {value} has no instance; available: {[(i.id,i.port) for i in instances]}')","typeGuard":"def port_known(value: str, ports: set[int]) -> bool:\n    return not value.isdigit() or int(value) in ports","tryCatchPattern":"try:\n    await call_unity_tool(cmd, params, unity_instance=value)\nexcept ValueError as e:\n    if 'found on port' in str(e):\n        instances = await read_resource('mcpforunity://instances')\n        await call_unity_tool(cmd, params, unity_instance=instances[0]['id'])","preventionTips":["Prefer Name@hash over port (stable across restarts)","Re-read the status file after Unity restarts","Do not hardcode ports in client configs"],"tags":["validation","stdio","port","unity-instance"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}