microsoft/autogen · error · Exception

{serialized_error_message}

Error message

{serialized_error_message}

What it means

McpToolAdapter.run() executes the MCP tools/call and inspects result.isError. If the server reports an error, the content list is serialized to a string (via return_value_as_string) and raised as a plain Exception with that text. The message is server-authored — it is whatever the tool server put in its error content, not an AutoGen-generated message.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/tools/mcp/_base.py:124

        exceptions_to_catch: tuple[Type[BaseException], ...]
        if hasattr(builtins, "ExceptionGroup"):
            exceptions_to_catch = (asyncio.CancelledError, builtins.ExceptionGroup)
        else:
            exceptions_to_catch = (asyncio.CancelledError,)

        try:
            if cancellation_token.is_cancelled():
                raise asyncio.CancelledError("Operation cancelled")

            result_future = asyncio.ensure_future(session.call_tool(name=self._tool.name, arguments=args))
            cancellation_token.link_future(result_future)
            result = await result_future

            normalized_content_list = self._normalize_payload_to_content_list(result.content)

            if result.isError:
                serialized_error_message = self.return_value_as_string(normalized_content_list)
                raise Exception(serialized_error_message)
            return normalized_content_list

        except exceptions_to_catch:
            # Re-raise these specific exception types directly.
            raise

    @classmethod
    async def from_server_params(cls, server_params: TServerParams, tool_name: str) -> "McpToolAdapter[TServerParams]":
        """
        Create an instance of McpToolAdapter from server parameters and tool name.

        Args:
            server_params (TServerParams): Parameters for the MCP server connection.
            tool_name (str): The name of the tool to wrap.

        Returns:
            McpToolAdapter[TServerParams]: An instance of McpToolAdapter.

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Read the exception message — it contains the serialized server error content; fix the argument or environment issue it describes.
2. Print/capture the tool's input schema (from list_tools) and validate arguments against it before calling run().
3. If the error is transient (rate limit, timeout), catch the Exception and retry with backoff.
4. For agent workflows, let the error propagate into the model's tool-call result so it can self-correct the arguments.

Example fix

# before
result = await tool.run(args, cancellation_token)  # raises Exception(server message)

# after
from autogen_core.tools import BaseTool

try:
    result = await tool.run(args, cancellation_token)
except Exception as e:
    # surface server-authored message to the agent or retry logic
    tool_error = str(e)
    raise ToolCallFailed(tool_error) from e

schema = tool._tool.inputSchema
required = set(schema.get("required", []))
missing = required - set(args.model_dump(exclude_none=True))
if missing:
    raise ValueError(f"missing required tool args: {sorted(missing)}")

try:
    result = await tool.run(args, cancellation_token)
except Exception as e:  # server-authored isError content
    error_text = str(e)
    logger.warning("MCP tool %s failed: %s", tool.name, error_text)
    if is_transient(error_text):  # e.g. rate limit, 429, timeout
        await asyncio.sleep(backoff)
        return await tool.run(args, cancellation_token)
    return [TextContent(type="text", text=f"Tool error: {error_text}")]

When it happens

Trigger: Any tool execution where the MCP server sets isError=true on the CallToolResult: invalid arguments per the server's own schema, upstream API failures inside the tool, missing resources, permission errors on the server side.

Common situations: Calling an MCP tool with argument values the server validates more strictly than the advertised schema; the wrapped third-party API returning 4xx/5xx; expired credentials on the server; tool expecting a file/env var absent in the server's environment.

Related errors

• name is required for call_tool
• Failed to list MCP tools
• Failed to call MCP tool
• MCP health check failed
• HTTP ${response.status}: ${errorText || "Failed to create We

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