{"record":{"id":"cf9bd8f08e9120ef","repo":"mastra-ai/mastra","slug":"mcp-client-on-list-changed-resource-failed","errorCode":"MCP_CLIENT_ON_LIST_CHANGED_RESOURCE_FAILED","errorMessage":"MCP_CLIENT_ON_LIST_CHANGED_RESOURCE_FAILED","messagePattern":"MCP_CLIENT_ON_LIST_CHANGED_RESOURCE_FAILED","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/configuration.ts","lineNumber":518,"sourceCode":"       * @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\n       * @throws {MastraError} If setting up the handler fails\n       *\n       * @example\n       * ```typescript\n       * await mcp.resources.onListChanged('weatherServer', async () => {\n       *   console.log('Resource list changed, re-fetching...');\n       *   const resources = await mcp.resources.list();\n       * });\n       * ```\n       */\n      onListChanged: async (serverName: string, handler: () => void) => {\n        try {\n          const internalClient = await this.getConnectedClientForServer(serverName);\n          return internalClient.resources.onListChanged(handler);\n        } catch (err) {\n          throw new MastraError(\n            {\n              id: 'MCP_CLIENT_ON_LIST_CHANGED_RESOURCE_FAILED',\n              domain: ErrorDomain.MCP,\n              category: ErrorCategory.THIRD_PARTY,\n              details: {\n                serverName,\n              },\n            },\n            err,\n          );\n        }\n      },\n    };\n  }\n\n  /**\n   * Provides access to prompt-related operations across all configured servers.\n   *","sourceCodeStart":500,"sourceCodeEnd":536,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/configuration.ts#L500-L536","documentation":"Thrown when registering a handler for the resources/list_changed notification fails: MCPClient's resources.onListChanged(serverName, handler) connects and attaches the handler on the internal client; failures are wrapped in a MastraError with id MCP_CLIENT_ON_LIST_CHANGED_RESOURCE_FAILED (category THIRD_PARTY). This notification tells you when the server's set of available resources changes.","triggerScenarios":"Calling mcpClient.resources.onListChanged('myServer', handler) when the server name is unknown, the server cannot be connected (bad transport config, failed spawn), or the internal onListChanged registration throws.","commonSituations":"Server name typo; handler registered before the client ever connected to the server; server restarted or crashed so the lookup fails; npx-based server failed to download its package in a sandboxed/CI environment.","solutions":["Verify serverName matches the servers configuration key exactly.","Get the server connected first (test the command/args manually; check env, PATH, network) then register the handler.","Re-register handlers after any reconnect, since handlers live on the in-memory internal client.","Catch the error and fall back to polling resources.list() when change notifications can't be installed."],"exampleFix":"// before\nawait mcp.resources.onListChanged('Docs', sync); // config key is 'docs'\n// after\nawait mcp.resources.onListChanged('docs', sync);","handlingStrategy":"try-catch","validationCode":"const configured = Object.keys(serversConfig);\nif (!configured.includes(serverName)) throw new Error(`server not configured: ${serverName}`);","typeGuard":"function isOnListChangedError(e: unknown): e is MastraError {\n  return e instanceof MastraError && e.id === 'MCP_CLIENT_ON_LIST_CHANGED_RESOURCE_FAILED';\n}","tryCatchPattern":"try {\n  await mcp.resources.onListChanged(serverName, syncResourceList);\n} catch (e) {\n  if (isOnListChangedError(e)) {\n    logger.warn(`list-changed notifications unavailable for ${e.details?.serverName}; will poll resources.list`, e);\n    startListPolling(serverName);\n    return;\n  }\n  throw e;\n}","preventionTips":["Verify the server connects before registering list-changed handlers (test the spawn command in CI/sandboxes).","Use config-derived server names, not literals, to avoid typos.","Refresh handler registrations on every reconnect.","Degrade to periodic resources.list() polling when notifications can't be installed."],"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-30T08:17:16.595Z"}