mastra-ai/mastra · error · MastraError

MCP_CLIENT_TOOL_HYDRATION_FAILED

MCP_CLIENT_TOOL_HYDRATION_FAILED

Error message

Failed to rebuild MCP tool "${definition.name}" from its cached definition

What it means

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.

Source

Thrown at packages/mcp/src/client/client.ts:1328

   */
  toolFromDefinition({ definition }: { definition: SerializableMCPToolDefinition }): Tool<any, any, any, any> {
    const tool = {
      name: definition.name,
      description: definition.description,
      inputSchema: definition.inputSchema,
      outputSchema: definition.outputSchema,
      annotations: definition.annotations,
      _meta: definition._meta,
    } as MCPToolListEntry;

    const built = this.buildToolFromListEntry(tool, {
      version: definition.server.version,
      instructions: definition.server.instructions,
      connectFirst: true,
    });

    if (!built) {
      throw new MastraError({
        id: 'MCP_CLIENT_TOOL_HYDRATION_FAILED',
        domain: ErrorDomain.MCP,
        category: ErrorCategory.USER,
        text: `Failed to rebuild MCP tool "${definition.name}" from its cached definition`,
        details: { toolName: definition.name, serverName: this.name },
      });
    }

    return built;
  }

  async tools(): Promise<Record<string, Tool<any, any, any, any>>> {
    this.log('debug', `Requesting tools from MCP server`);
    const { tools } = await this.client.listTools({}, { timeout: this.timeout });
    const toolsRes: Record<string, Tool<any, any, any, any>> = {};
    for (const tool of tools) {
      this.log('debug', `Processing tool: ${tool.name}`);
      const mastraTool = this.buildToolFromListEntry(tool, {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Clear/delete the cached tool definitions so the client re-discovers tools fresh from the server (restart the client/agent with a clean cache).
2. 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.
3. 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.
4. Ensure the server connects successfully (check serverName, transport config); a failed connection can make the rebuild return nothing.

Example fix

// before: agent holds a stale cached tool
await mcpToolset.getTool('queryDatabase')(); // throws MCP_CLIENT_TOOL_HYDRATION_FAILED
// after: disconnect and reconnect to refresh cached definitions
await mcpClient.disconnect();
await mcpClient.getToolsets(); // re-discovers current tools from the server

// Before calling a cached tool, confirm the server still lists it
const tools = await toolset.listTools(); // or MCP inspector
if (!tools.some(t => t.name === cachedToolName)) {
  await mcpClient.disconnect(); // force fresh discovery
  // re-fetch toolsets and rebind tools
}

function isHydrationFailure(e: unknown): e is { id: string; details: { toolName: string; serverName: string } } {
  return e instanceof MastraError && e.id === 'MCP_CLIENT_TOOL_HYDRATION_FAILED';
}

try {
  const result = await cachedTool.execute(args);
} catch (e) {
  if (isHydrationFailure(e)) {
    await mcpClient.disconnect();
    toolset = await mcpClient.getToolsets(); // re-discover and rebind
    return rebindAndRun(cachedTool.name, args);
  }
  throw e;
}

When it happens

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

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

Related errors

• ${key} exists but is not a number
• Unsupported file extension: ${targzPath}
• No arguments provided
• Invalid arguments for firecrawl_scrape
• Invalid arguments for firecrawl_map

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/8d8b9c3304ccc92c. Report an issue: GitHub.