{"record":{"id":"aae7c40145725442","repo":"CoplayDev/unity-mcp","slug":"unity-instance-value-must-not-be-empty","errorCode":null,"errorMessage":"unity_instance value must not be empty.","messagePattern":"unity_instance value must not be empty\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Server/src/transport/unity_instance_middleware.py","lineNumber":154,"sourceCode":"                    raise\n                logger.debug(\"Stdio instance discovery failed (%s)\", type(exc).__name__, exc_info=True)\n\n        return results\n\n    async def _resolve_instance_value(self, value: str, ctx) -> str:\n        \"\"\"\n        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","sourceCodeStart":136,"sourceCodeEnd":172,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/transport/unity_instance_middleware.py#L136-L172","documentation":"Raised by UnityInstanceMiddleware.resolve when the supplied unity_instance string is empty after stripping whitespace. It is an input-validation guard at the top of the resolver so downstream port/hash lookups never see a blank value.","triggerScenarios":"A tool call passes unity_instance='' or a whitespace-only string (e.g. a UI field left blank, or a templated value that resolved to empty). The strip() check at unity_instance_middleware.py:152-154 fails.","commonSituations":"Client binds an empty env var into the unity_instance argument; a script interpolates an unset variable; the user cleared the active-instance field but the client still sent the key with an empty value.","solutions":["Omit the unity_instance argument entirely so the middleware auto-selects, rather than sending an empty string.","Validate the argument is non-empty before constructing the tool call.","Fix the upstream source of the value (env var, config, UI field) so it carries a real Name@hash or hash prefix."],"exampleFix":"// before\nunity_instance = os.environ.get('UNITY_INSTANCE', '')  # '' when unset\nawait call_unity_tool('manage_gameobject', {...}, unity_instance=unity_instance)\n// after\nunity_instance = os.environ.get('UNITY_INSTANCE') or None\nawait call_unity_tool('manage_gameobject', {...}, unity_instance=unity_instance)","handlingStrategy":"validation","validationCode":"if unity_instance is not None:\n    assert unity_instance.strip(), 'unity_instance must be non-empty if provided'\nunity_instance = unity_instance.strip() or None","typeGuard":"def is_valid_instance_token(v: str | None) -> bool:\n    return v is None or v.strip() != ''","tryCatchPattern":"try:\n    await call_unity_tool(cmd, params, unity_instance=unity_instance)\nexcept ValueError as e:\n    if 'must not be empty' in str(e):\n        unity_instance = None\n        await call_unity_tool(cmd, params)","preventionTips":["Normalize empty strings to None before passing unity_instance","Omit the argument entirely for auto-selection","Validate UI fields before binding them to the call"],"tags":["validation","input","unity-instance"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}