{"record":{"id":"fd896cd2554cc163","repo":"microsoft/autogen","slug":"serialized-error-message","errorCode":null,"errorMessage":"{serialized_error_message}","messagePattern":"\\{serialized_error_message\\}","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/tools/mcp/_base.py","lineNumber":124,"sourceCode":"        exceptions_to_catch: tuple[Type[BaseException], ...]\n        if hasattr(builtins, \"ExceptionGroup\"):\n            exceptions_to_catch = (asyncio.CancelledError, builtins.ExceptionGroup)\n        else:\n            exceptions_to_catch = (asyncio.CancelledError,)\n\n        try:\n            if cancellation_token.is_cancelled():\n                raise asyncio.CancelledError(\"Operation cancelled\")\n\n            result_future = asyncio.ensure_future(session.call_tool(name=self._tool.name, arguments=args))\n            cancellation_token.link_future(result_future)\n            result = await result_future\n\n            normalized_content_list = self._normalize_payload_to_content_list(result.content)\n\n            if result.isError:\n                serialized_error_message = self.return_value_as_string(normalized_content_list)\n                raise Exception(serialized_error_message)\n            return normalized_content_list\n\n        except exceptions_to_catch:\n            # Re-raise these specific exception types directly.\n            raise\n\n    @classmethod\n    async def from_server_params(cls, server_params: TServerParams, tool_name: str) -> \"McpToolAdapter[TServerParams]\":\n        \"\"\"\n        Create an instance of McpToolAdapter from server parameters and tool name.\n\n        Args:\n            server_params (TServerParams): Parameters for the MCP server connection.\n            tool_name (str): The name of the tool to wrap.\n\n        Returns:\n            McpToolAdapter[TServerParams]: An instance of McpToolAdapter.\n","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_base.py#L106-L142","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the exception message — it contains the serialized server error content; fix the argument or environment issue it describes.","Print/capture the tool's input schema (from list_tools) and validate arguments against it before calling run().","If the error is transient (rate limit, timeout), catch the Exception and retry with backoff.","For agent workflows, let the error propagate into the model's tool-call result so it can self-correct the arguments."],"exampleFix":"# before\nresult = await tool.run(args, cancellation_token)  # raises Exception(server message)\n\n# after\nfrom autogen_core.tools import BaseTool\n\ntry:\n    result = await tool.run(args, cancellation_token)\nexcept Exception as e:\n    # surface server-authored message to the agent or retry logic\n    tool_error = str(e)\n    raise ToolCallFailed(tool_error) from e","handlingStrategy":"try-catch","validationCode":"schema = tool._tool.inputSchema\nrequired = set(schema.get(\"required\", []))\nmissing = required - set(args.model_dump(exclude_none=True))\nif missing:\n    raise ValueError(f\"missing required tool args: {sorted(missing)}\")","typeGuard":null,"tryCatchPattern":"try:\n    result = await tool.run(args, cancellation_token)\nexcept Exception as e:  # server-authored isError content\n    error_text = str(e)\n    logger.warning(\"MCP tool %s failed: %s\", tool.name, error_text)\n    if is_transient(error_text):  # e.g. rate limit, 429, timeout\n        await asyncio.sleep(backoff)\n        return await tool.run(args, cancellation_token)\n    return [TextContent(type=\"text\", text=f\"Tool error: {error_text}\")]","preventionTips":["Validate arguments against the tool's inputSchema before calling run().","Return tool errors to the agent as text results so the model can correct its arguments.","Distinguish transient (rate limit/timeout) from permanent (validation) errors before retrying."],"tags":["mcp","tool-call","server-error","runtime"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}