{"record":{"id":"52f92309107febf4","repo":"mastra-ai/mastra","slug":"mcp-client-on-list-changed-prompt-failed","errorCode":"MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED","errorMessage":"MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED","messagePattern":"MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/configuration.ts","lineNumber":639,"sourceCode":"       * @param serverName - Name of the server to monitor\n       * @param handler - Callback function invoked when prompts are added/removed/modified\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.prompts.onListChanged('weatherServer', async () => {\n       *   console.log('Prompt list changed, re-fetching...');\n       *   const prompts = await mcp.prompts.list();\n       * });\n       * ```\n       */\n      onListChanged: async (serverName: string, handler: () => void) => {\n        try {\n          const internalClient = await this.getConnectedClientForServer(serverName);\n          return internalClient.prompts.onListChanged(handler);\n        } catch (error) {\n          throw new MastraError(\n            {\n              id: 'MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED',\n              domain: ErrorDomain.MCP,\n              category: ErrorCategory.THIRD_PARTY,\n              details: {\n                serverName,\n              },\n            },\n            error,\n          );\n        }\n      },\n    };\n  }\n\n  /**\n   * Provides access to tool-related notification operations across all configured servers.\n   *","sourceCodeStart":621,"sourceCodeEnd":657,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/configuration.ts#L621-L657","documentation":"MastraError thrown when registering a prompt list-changed notification handler fails. The client must first obtain a connected internal client for the named server before attaching the handler via internalClient.prompts.onListChanged; connection failures are wrapped in this error. It signals that change notifications for prompts cannot be subscribed to for that server.","triggerScenarios":"Calling mcpClient.prompts.onListChanged(serverName, handler) when getConnectedClientForServer(serverName) throws (unknown server name, connection not established, server unreachable).","commonSituations":"Subscribing before the client has connected to the server; misspelled server name; server process down; registering handlers during startup races where connection has not completed.","solutions":["Ensure the server is configured and a connection is established before registering the handler.","Check the serverName spelling against your MCPClient configuration.","Await client connection/initialization (or use getConnectedClientForServer semantics) prior to subscription.","Retry the subscription after reconnecting if the server was temporarily down."],"exampleFix":"// before\nclient.prompts.onListChanged('myserver', () => refresh());\n// after\nawait client.getConnectedClientForServer('myserver'); // ensure connection first\nclient.prompts.onListChanged('myserver', () => refresh());","handlingStrategy":"try-catch","validationCode":"if (!Object.keys(configuredServers).includes(serverName)) throw new Error(`unknown server ${serverName}`);\nawait client.getConnectedClientForServer(serverName); // throws early if unreachable","typeGuard":null,"tryCatchPattern":"try {\n  client.prompts.onListChanged(serverName, handler);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED') {\n    scheduleRetry(() => client.prompts.onListChanged(serverName, handler));\n  } else throw e;\n}","preventionTips":["Subscribe only after the server connection is established.","Keep a single source of truth for server names (constants/enums).","Add reconnect hooks that re-register notification handlers.","Log the wrapped cause to distinguish naming vs transport issues."],"tags":["mcp","prompts","notification","connection"],"backgroundTag":"mcp-subscription-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}