CoplayDev/unity-mcp · error · ValueError

Command '{tool_name}' at index {index} contains 'unity_insta

Error message

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.

What it means

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.

Source

Thrown at Server/src/services/tools/batch_execute.py:120

        if not isinstance(command, dict):
            raise ValueError(
                f"Command at index {index} must be an object with 'tool' and 'params' keys")

        tool_name = command.get("tool")
        params = command.get("params", {})

        if not tool_name or not isinstance(tool_name, str):
            raise ValueError(
                f"Command at index {index} is missing a valid 'tool' name")

        if params is None:
            params = {}
        if not isinstance(params, dict):
            raise ValueError(
                f"Command '{tool_name}' must specify parameters as an object/dict")

        if "unity_instance" in params:
            raise ValueError(
                f"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."
            )

        normalized_commands.append({
            "tool": tool_name,
            "params": params,
        })

    payload: dict[str, Any] = {
        "commands": normalized_commands,
    }

    if parallel is not None:
        payload["parallel"] = bool(parallel)
    if fail_fast is not None:
        payload["failFast"] = bool(fail_fast)

View on GitHub (pinned to c21bf496bc)

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.

Example fix

// before
commands=[{"tool": "manage_gameobject", "params": {"action": "create", "unity_instance": "Proj@abcd1234"}}]
// after
commands=[{"tool": "manage_gameobject", "params": {"action": "create"}}]
// (instance is resolved from the outer batch_execute context)

Defensive patterns

Strategy: validation

Validate before calling

# Strip any per-command unity_instance before batching
for i, c in enumerate(commands):
    params = c.get("params", {})
    if isinstance(params, dict) and "unity_instance" in params:
        del params["unity_instance"]
        print(f"Removed unity_instance from command {i} ({c.get('tool')}); set it on the outer batch_execute context.")

Type guard

def no_per_command_instance(commands: list) -> bool:
    return all(
        "unity_instance" not in (c.get("params") or {})
        for c in commands
        if isinstance(c, dict)
    )

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/58a5720eb64c18c3. Report an issue: GitHub.