{"record":{"id":"8d8b9c3304ccc92c","repo":"mastra-ai/mastra","slug":"mcp-client-tool-hydration-failed","errorCode":"MCP_CLIENT_TOOL_HYDRATION_FAILED","errorMessage":"Failed to rebuild MCP tool \"${definition.name}\" from its cached definition","messagePattern":"Failed to rebuild MCP tool \"(.+?)\" from its cached definition","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/client.ts","lineNumber":1328,"sourceCode":"   */\n  toolFromDefinition({ definition }: { definition: SerializableMCPToolDefinition }): Tool<any, any, any, any> {\n    const tool = {\n      name: definition.name,\n      description: definition.description,\n      inputSchema: definition.inputSchema,\n      outputSchema: definition.outputSchema,\n      annotations: definition.annotations,\n      _meta: definition._meta,\n    } as MCPToolListEntry;\n\n    const built = this.buildToolFromListEntry(tool, {\n      version: definition.server.version,\n      instructions: definition.server.instructions,\n      connectFirst: true,\n    });\n\n    if (!built) {\n      throw new MastraError({\n        id: 'MCP_CLIENT_TOOL_HYDRATION_FAILED',\n        domain: ErrorDomain.MCP,\n        category: ErrorCategory.USER,\n        text: `Failed to rebuild MCP tool \"${definition.name}\" from its cached definition`,\n        details: { toolName: definition.name, serverName: this.name },\n      });\n    }\n\n    return built;\n  }\n\n  async tools(): Promise<Record<string, Tool<any, any, any, any>>> {\n    this.log('debug', `Requesting tools from MCP server`);\n    const { tools } = await this.client.listTools({}, { timeout: this.timeout });\n    const toolsRes: Record<string, Tool<any, any, any, any>> = {};\n    for (const tool of tools) {\n      this.log('debug', `Processing tool: ${tool.name}`);\n      const mastraTool = this.buildToolFromListEntry(tool, {","sourceCodeStart":1310,"sourceCodeEnd":1346,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/client.ts#L1310-L1346","documentation":"Thrown when a cached MCP tool definition (persisted from a previous session) cannot be rebuilt into a live, callable tool when the client reconnects to its server. The library hydrates tools from their stored definitions (name, schema, server info) so agents can keep using tools across restarts; if the rebuild returns nothing (e.g. the server no longer exposes that tool, or the definition is stale/corrupt), this MastraError with id MCP_CLIENT_TOOL_HYDRATION_FAILED is raised. It is categorized as USER because the cached definition no longer matches what the server provides.","triggerScenarios":"Calling a tool that was previously discovered and cached by InternalMastraMCPClient; on reconnect the client calls the tool-builder with connectFirst: true and the builder returns falsy — typically because the MCP server was upgraded/downgraded and removed or renamed the tool, or the cached definition references a server/tool that no longer exists.","commonSituations":"MCP server upgraded and a tool was removed or renamed; switching between server versions in dev; a corrupted or hand-edited tool cache; hot-reloading dev servers that re-register toolsets; stale persisted agent state pointing at an old tool.","solutions":["Clear/delete the cached tool definitions so the client re-discovers tools fresh from the server (restart the client/agent with a clean cache).","Verify the MCP server still exposes the tool: check its tool list (e.g. via an MCP inspector or listTools) and update your agent/config to the current tool name.","If the server version changed intentionally, re-run your setup so new definitions are cached, and update any persisted agent instructions referencing the old tool.","Ensure the server connects successfully (check serverName, transport config); a failed connection can make the rebuild return nothing."],"exampleFix":"// before: agent holds a stale cached tool\nawait mcpToolset.getTool('queryDatabase')(); // throws MCP_CLIENT_TOOL_HYDRATION_FAILED\n// after: disconnect and reconnect to refresh cached definitions\nawait mcpClient.disconnect();\nawait mcpClient.getToolsets(); // re-discovers current tools from the server","handlingStrategy":"try-catch","validationCode":"// Before calling a cached tool, confirm the server still lists it\nconst tools = await toolset.listTools(); // or MCP inspector\nif (!tools.some(t => t.name === cachedToolName)) {\n  await mcpClient.disconnect(); // force fresh discovery\n  // re-fetch toolsets and rebind tools\n}","typeGuard":"function isHydrationFailure(e: unknown): e is { id: string; details: { toolName: string; serverName: string } } {\n  return e instanceof MastraError && e.id === 'MCP_CLIENT_TOOL_HYDRATION_FAILED';\n}","tryCatchPattern":"try {\n  const result = await cachedTool.execute(args);\n} catch (e) {\n  if (isHydrationFailure(e)) {\n    await mcpClient.disconnect();\n    toolset = await mcpClient.getToolsets(); // re-discover and rebind\n    return rebindAndRun(cachedTool.name, args);\n  }\n  throw e;\n}","preventionTips":["Disconnect and reconnect (or clear caches) after upgrading an MCP server so definitions re-sync.","Reference tools dynamically from the server's tool list instead of persisting tool names across versions.","Pin MCP server versions in config so tool sets don't shift unexpectedly.","Log tool lists at startup and alert when a previously used tool disappears."],"tags":["mcp","cache","hydration","tool-resolution"],"backgroundTag":"stale-cache-entry","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}