{"record":{"id":"58a5720eb64c18c3","repo":"CoplayDev/unity-mcp","slug":"command-tool-name-at-index-index-contains-u","errorCode":null,"errorMessage":"Command '{tool_name}' at index {index} contains 'unity_instance'. Per-command instance routing is not supported inside batch_execute. Set unity_instance on the outer batch_execute call to route the entire batch.","messagePattern":"Command '(.+?)' at index (.+?) contains 'unity_instance'\\. Per-command instance routing is not supported inside batch_execute\\. Set unity_instance on the outer batch_execute call to route the entire batch\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"Server/src/services/tools/batch_execute.py","lineNumber":120,"sourceCode":"        if not isinstance(command, dict):\n            raise ValueError(\n                f\"Command at index {index} must be an object with 'tool' and 'params' keys\")\n\n        tool_name = command.get(\"tool\")\n        params = command.get(\"params\", {})\n\n        if not tool_name or not isinstance(tool_name, str):\n            raise ValueError(\n                f\"Command at index {index} is missing a valid 'tool' name\")\n\n        if params is None:\n            params = {}\n        if not isinstance(params, dict):\n            raise ValueError(\n                f\"Command '{tool_name}' must specify parameters as an object/dict\")\n\n        if \"unity_instance\" in params:\n            raise ValueError(\n                f\"Command '{tool_name}' at index {index} contains 'unity_instance'. \"\n                \"Per-command instance routing is not supported inside batch_execute. \"\n                \"Set unity_instance on the outer batch_execute call to route the entire batch.\"\n            )\n\n        normalized_commands.append({\n            \"tool\": tool_name,\n            \"params\": params,\n        })\n\n    payload: dict[str, Any] = {\n        \"commands\": normalized_commands,\n    }\n\n    if parallel is not None:\n        payload[\"parallel\"] = bool(parallel)\n    if fail_fast is not None:\n        payload[\"failFast\"] = bool(fail_fast)","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/CoplayDev/unity-mcp/blob/c21bf496bca87d54e75bad048563c3adb1782081/Server/src/services/tools/batch_execute.py#L102-L138","documentation":"In batch_execute, no individual command's params may contain the key 'unity_instance'. The entire batch is routed to a single Unity instance (resolved from the outer batch_execute call's context), so per-command instance routing is explicitly forbidden to prevent ambiguity and cross-instance side effects. This guard rejects the key regardless of its value. The tool_name and index are included in the message.","triggerScenarios":"A caller includes \"unity_instance\": \"Project@hash\" inside a sub-command's params, attempting to route that one command to a different Unity instance; an LLM copies a standalone tool call (which accepts unity_instance) into a batch without stripping the key; a caller tries to mix instances in one batch.","commonSituations":"An AI wraps existing tool calls (that include unity_instance) into a batch for efficiency, forgetting to remove the per-call instance key; a caller assumes batch_execute supports heterogeneous instance routing; copy-paste from single-tool invocations.","solutions":["Remove the 'unity_instance' key from every sub-command's params.","Set the Unity instance once at the batch_execute level via the tool context (the outer call resolves the instance).","If you need to target multiple instances, issue separate batch_execute calls, one per instance."],"exampleFix":"// before\ncommands=[{\"tool\": \"manage_gameobject\", \"params\": {\"action\": \"create\", \"unity_instance\": \"Proj@abcd1234\"}}]\n// after\ncommands=[{\"tool\": \"manage_gameobject\", \"params\": {\"action\": \"create\"}}]\n// (instance is resolved from the outer batch_execute context)","handlingStrategy":"validation","validationCode":"# Strip any per-command unity_instance before batching\nfor i, c in enumerate(commands):\n    params = c.get(\"params\", {})\n    if isinstance(params, dict) and \"unity_instance\" in params:\n        del params[\"unity_instance\"]\n        print(f\"Removed unity_instance from command {i} ({c.get('tool')}); set it on the outer batch_execute context.\")","typeGuard":"def no_per_command_instance(commands: list) -> bool:\n    return all(\n        \"unity_instance\" not in (c.get(\"params\") or {})\n        for c in commands\n        if isinstance(c, dict)\n    )","tryCatchPattern":null,"preventionTips":["Never include 'unity_instance' inside a sub-command's params.","Set the Unity instance once at the batch_execute level via the tool context.","When wrapping standalone tool calls into a batch, strip the unity_instance key from each."],"tags":["validation","batch-execute","instance-routing","security","mcp-tool"],"backgroundTag":null,"analyzedSha":"c21bf496bca87d54e75bad048563c3adb1782081","analyzedAt":"2026-08-13T17:36:56.095Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}