{"record":{"id":"b927868a404d2290","repo":"CoplayDev/unity-mcp","slug":"port-based-targeting-value-is-not-supported","errorCode":null,"errorMessage":"Port-based targeting ('{value}') is not supported in HTTP transport mode. Use Name@hash or a hash prefix. Read mcpforunity://instances for available instances.","messagePattern":"Port-based targeting \\('(.+?)'\\) is not supported in HTTP transport mode\\. Use Name@hash or a hash prefix\\. Read mcpforunity://instances for available instances\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/unity_instance_middleware.py","lineNumber":161,"sourceCode":"        Resolve a unity_instance string to a validated instance identifier.\n\n        Accepts:\n          - Bare port number like \"6401\" (stdio only) -> resolved Name@hash\n          - \"Name@hash\" exact match\n          - Hash prefix (unique prefix match against running instances)\n\n        Raises ValueError with a user-friendly message on failure.\n        \"\"\"\n        value = value.strip()\n        if not value:\n            raise ValueError(\"unity_instance value must not be empty.\")\n\n        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 = {","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/unity_instance_middleware.py#L143-L179","documentation":"Raised by resolve when the user passed a bare port number (e.g. '6401') while the server is running in HTTP transport mode. Port-based targeting is a stdio-only convenience (it maps a port to a single local plugin via the status file); HTTP mode is multi-agent and requires a Name@hash or hash prefix instead.","triggerScenarios":"config.transport_mode == 'http' and the unity_instance argument value.isdigit() is true. The guard at unity_instance_middleware.py:158-162 fires.","commonSituations":"Switched a deployment from stdio to HTTP transport but reused client configs that targeted by port; a tutorial/copy-paste carried over a stdio port value into an HTTP setup.","solutions":["Read mcpforunity://instances and pass a Name@hash (or unique hash prefix) instead of the port.","Switch the server back to stdio transport if per-port targeting is required.","Update any client config templates that hardcode a port so they read the instances resource."],"exampleFix":"// before (http mode)\nawait call_unity_tool('manage_gameobject', {...}, unity_instance='6401')\n// after\nawait call_unity_tool('manage_gameobject', {...}, unity_instance='UnityMCPTests@a1b2c3d4')","handlingStrategy":"validation","validationCode":"if config.transport_mode == 'http' and value and value.isdigit():\n    raise ValueError('Use Name@hash in HTTP mode, not a port')","typeGuard":"def is_http_safe_target(value: str, transport: str) -> bool:\n    return not (transport == 'http' and value.isdigit())","tryCatchPattern":"try:\n    await call_unity_tool(cmd, params, unity_instance=value)\nexcept ValueError as e:\n    if 'not supported in HTTP transport' in str(e):\n        instances = await read_resource('mcpforunity://instances')\n        await call_unity_tool(cmd, params, unity_instance=instances[0]['id'])","preventionTips":["Standardize on Name@hash targeting across transports","Detect transport mode in client config and reject port values in HTTP","Keep config templates port-free"],"tags":["validation","transport","http","unity-instance"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}