mastra-ai/mastra · error · MastraError

MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED

MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED

Error message

MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED

What it means

Thrown when registering a handler for resource-updated notifications fails: MCPClient's resources.onUpdated(serverName, handler) connects and attaches the handler on the internal client; failures are wrapped in a MastraError with id MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED (category THIRD_PARTY). This is the notification path for changes to resources you are subscribed to.

Source

Thrown at packages/mcp/src/client/configuration.ts:484

       * @param serverName - Name of the server to monitor
       * @param handler - Callback function receiving the updated resource URI
       * @returns Promise resolving when handler is registered
       * @throws {MastraError} If setting up the handler fails
       *
       * @example
       * ```typescript
       * await mcp.resources.onUpdated('weatherServer', async (params) => {
       *   console.log(`Resource updated: ${params.uri}`);
       *   const content = await mcp.resources.read('weatherServer', params.uri);
       * });
       * ```
       */
      onUpdated: async (serverName: string, handler: (params: { uri: string }) => void) => {
        try {
          const internalClient = await this.getConnectedClientForServer(serverName);
          return internalClient.resources.onUpdated(handler);
        } catch (err) {
          throw new MastraError(
            {
              id: 'MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED',
              domain: ErrorDomain.MCP,
              category: ErrorCategory.THIRD_PARTY,
              details: {
                serverName,
              },
            },
            err,
          );
        }
      },
      /**
       * Sets a notification handler for when the resource list changes on a server.
       *
       * @param serverName - Name of the server to monitor
       * @param handler - Callback function invoked when resources are added/removed
       * @returns Promise resolving when handler is registered

View on GitHub (pinned to 75dd419e61)

Solutions

1. Confirm serverName matches a key in the MCPClient servers configuration.
2. Ensure the server connects successfully: verify command/args/url, run it manually, and check logs; then register the handler.
3. Register notification handlers right after client setup and re-register after reconnects (connection loss clears in-memory handlers).
4. Catch this error and continue without change notifications (fall back to polling) since it's optional realtime telemetry.

Example fix

// before: handler registered before server ever connects; name mismatch
await mcp.resources.onUpdated('docs-server', onChange); // configured as 'docs'
// after
await mcp.resources.onUpdated('docs', onChange);

const configured = Object.keys(serversConfig);
if (!configured.includes(serverName)) throw new Error(`server not configured: ${serverName}`);

function isOnUpdatedError(e: unknown): e is MastraError {
  return e instanceof MastraError && e.id === 'MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED';
}

try {
  await mcp.resources.onUpdated(serverName, onChange);
} catch (e) {
  if (isOnUpdatedError(e)) {
    logger.warn(`resource-change notifications unavailable for ${e.details?.serverName}; polling instead`, e);
    startPolling(serverName); // graceful degradation
    return;
  }
  throw e;
}

When it happens

Trigger: Calling mcpClient.resources.onUpdated('myServer', handler) when the server is not configured under that name, cannot be connected (spawn/transport failure, crash), or the internal onUpdated registration throws.

Common situations: Server name typo; calling onUpdated before any connection to that server exists; server process died between subscribe and onUpdated; environment where the server binary isn't installed (npx download failure).

Related errors

• MCP_CLIENT_ON_LIST_CHANGED_RESOURCE_FAILED
• Failed to fetch resources from server ${this.client.name}: $
• Failed to fetch resource templates from server ${this.client
• MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED
• MCP_CLIENT_ON_REQUEST_ELICITATION_FAILED

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