microsoft/autogen · error · ValueError

Unknown command type: {type}

Error message

Unknown command type: {type}

What it means

McpActor.call() only recognizes a fixed command vocabulary: list_tools, list_prompts, list_resources, list_resource_templates, shutdown, call_tool, read_resource, get_prompt. Anything else falls to the final else and raises ValueError(f'Unknown command type: {type}'). Note this shadows the builtin type name because the parameter is called 'type' — the message interpolates the string you passed.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/tools/mcp/_actor.py:128

            name = args.get("name", None)
            kwargs = args.get("kargs", {})
            if type == "call_tool" and name is None:
                raise ValueError("name is required for call_tool")
            elif type == "read_resource":
                uri = kwargs.get("uri", None)
                if uri is None:
                    raise ValueError("uri is required for read_resource")
                await self._command_queue.put({"type": type, "uri": uri, "future": fut})
            elif type == "get_prompt":
                if name is None:
                    raise ValueError("name is required for get_prompt")
                prompt_args = kwargs.get("arguments", None)
                await self._command_queue.put({"type": type, "name": name, "args": prompt_args, "future": fut})
            else:  # call_tool
                await self._command_queue.put({"type": type, "name": name, "args": kwargs, "future": fut})
            res = await fut
        else:
            raise ValueError(f"Unknown command type: {type}")
        return res

    async def close(self) -> None:
        if not self._active or self._actor_task is None:
            return
        self._shutdown_future = asyncio.Future()
        await self._command_queue.put({"type": "shutdown", "future": self._shutdown_future})
        await self._shutdown_future
        await self._actor_task
        self._active = False

    async def _sampling_callback(
        self,
        context: RequestContext[ClientSession, Any],
        params: mcp_types.CreateMessageRequestParams,
    ) -> mcp_types.CreateMessageResult | mcp_types.ErrorData:
        """Handle sampling requests using the provided model client."""
        if self._host is None:

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Use one of the exact command strings: 'list_tools', 'list_prompts', 'list_resources', 'list_resource_templates', 'shutdown', 'call_tool', 'read_resource', 'get_prompt'.
2. If you need ping/notifications, go through the underlying MCP session object instead of the actor command queue.
3. Guard command strings with a constant set in your wrapper to fail early on typos.

Example fix

# before
await actor.call("tools/list")

# after
await actor.call("list_tools")

KNOWN = {
    "list_tools", "list_prompts", "list_resources", "list_resource_templates",
    "shutdown", "call_tool", "read_resource", "get_prompt",
}
if cmd not in KNOWN:
    raise ValueError(f"unknown actor command {cmd!r}; known: {sorted(KNOWN)}")

from typing import Literal

ActorCommand = Literal[
    "list_tools", "list_prompts", "list_resources", "list_resource_templates",
    "shutdown", "call_tool", "read_resource", "get_prompt",
]

When it happens

Trigger: Calling actor.call('tools/list') or 'ping' or a typo like 'list_tool' (singular); passing MCP protocol method names instead of the actor's internal command names.

Common situations: Translating raw MCP JSON-RPC method names from a server log into actor calls; singular/plural typos (list_tool vs list_tools); version skew where a newer command name is used against an older autogen-ext.

Related errors

• Failed to call MCP tool
• Invalid server URL configuration
• Unsupported built-in tool type: {tool_name}
• args is required for {type}
• name is required for call_tool

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/51428f2597196a5b. Report an issue: GitHub.