{"record":{"id":"101517dec39d857b","repo":"mastra-ai/mastra","slug":"mcp-client-on-updated-resource-failed","errorCode":"MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED","errorMessage":"MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED","messagePattern":"MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/configuration.ts","lineNumber":484,"sourceCode":"       * @param serverName - Name of the server to monitor\n       * @param handler - Callback function receiving the updated resource URI\n       * @returns Promise resolving when handler is registered\n       * @throws {MastraError} If setting up the handler fails\n       *\n       * @example\n       * ```typescript\n       * await mcp.resources.onUpdated('weatherServer', async (params) => {\n       *   console.log(`Resource updated: ${params.uri}`);\n       *   const content = await mcp.resources.read('weatherServer', params.uri);\n       * });\n       * ```\n       */\n      onUpdated: async (serverName: string, handler: (params: { uri: string }) => void) => {\n        try {\n          const internalClient = await this.getConnectedClientForServer(serverName);\n          return internalClient.resources.onUpdated(handler);\n        } catch (err) {\n          throw new MastraError(\n            {\n              id: 'MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED',\n              domain: ErrorDomain.MCP,\n              category: ErrorCategory.THIRD_PARTY,\n              details: {\n                serverName,\n              },\n            },\n            err,\n          );\n        }\n      },\n      /**\n       * Sets a notification handler for when the resource list changes on a server.\n       *\n       * @param serverName - Name of the server to monitor\n       * @param handler - Callback function invoked when resources are added/removed\n       * @returns Promise resolving when handler is registered","sourceCodeStart":466,"sourceCodeEnd":502,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/configuration.ts#L466-L502","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Confirm serverName matches a key in the MCPClient servers configuration.","Ensure the server connects successfully: verify command/args/url, run it manually, and check logs; then register the handler.","Register notification handlers right after client setup and re-register after reconnects (connection loss clears in-memory handlers).","Catch this error and continue without change notifications (fall back to polling) since it's optional realtime telemetry."],"exampleFix":"// before: handler registered before server ever connects; name mismatch\nawait mcp.resources.onUpdated('docs-server', onChange); // configured as 'docs'\n// after\nawait mcp.resources.onUpdated('docs', onChange);","handlingStrategy":"try-catch","validationCode":"const configured = Object.keys(serversConfig);\nif (!configured.includes(serverName)) throw new Error(`server not configured: ${serverName}`);","typeGuard":"function isOnUpdatedError(e: unknown): e is MastraError {\n  return e instanceof MastraError && e.id === 'MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED';\n}","tryCatchPattern":"try {\n  await mcp.resources.onUpdated(serverName, onChange);\n} catch (e) {\n  if (isOnUpdatedError(e)) {\n    logger.warn(`resource-change notifications unavailable for ${e.details?.serverName}; polling instead`, e);\n    startPolling(serverName); // graceful degradation\n    return;\n  }\n  throw e;\n}","preventionTips":["Register onUpdated right after successful client setup/connection.","Use shared constants for server names to prevent mismatches.","Re-register notification handlers after reconnects — they don't survive reconnection.","Treat change notifications as optional; keep a polling fallback."],"tags":["mcp","resources","notifications","event-handler"],"backgroundTag":"mcp-server-not-connected","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}