{"record":{"id":"bffa318f54bfebe1","repo":"mastra-ai/mastra","slug":"mcp-client-on-update-progress-failed","errorCode":"MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED","errorMessage":"MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED","messagePattern":"MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/configuration.ts","lineNumber":220,"sourceCode":"   * await mcp.progress.onUpdate('serverName', (params) => {\n   *   console.log(`Progress: ${params.progress}%`);\n   *   console.log(`Status: ${params.message}`);\n   *\n   *   if (params.total) {\n   *     console.log(`Completed ${params.progress} of ${params.total} items`);\n   *   }\n   * });\n   * ```\n   */\n  public get progress() {\n    this.addToInstanceCache();\n    return {\n      onUpdate: async (serverName: string, handler: (params: ProgressNotification['params']) => void) => {\n        try {\n          const internalClient = await this.getConnectedClientForServer(serverName);\n          return internalClient.progress.onUpdate(handler);\n        } catch (err) {\n          throw new MastraError(\n            {\n              id: 'MCP_CLIENT_ON_UPDATE_PROGRESS_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 elicitation-related operations for interactive user input collection.\n   *","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/configuration.ts#L202-L238","documentation":"Thrown when registering a progress notification handler fails: MCPClient's progress.onUpdate(serverName, handler) resolves the underlying InternalMastraMCPClient via getConnectedClientForServer and attaches the handler; any error in that lookup or attachment is wrapped in a MastraError with id MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED (category THIRD_PARTY). It means the progress-handler could not be installed for that server.","triggerScenarios":"Calling mcpClient.progress.onUpdate('myServer', handler) when the named server is not configured, is not connected/connectable (transport failure, process not started), or the internal client's progress.onUpdate call itself throws.","commonSituations":"Typo in serverName (key in the servers config vs the name passed to onUpdate); server process failed to spawn; calling onUpdate before the client ever connected to that server; server disconnected mid-session.","solutions":["Check serverName exactly matches a key in the MCPClient servers configuration (and that the client's serverName matches this.name on the internal client).","Ensure the server connects: run it manually/inspect its logs, verify command/args/url and env; fix the transport error first.","Register handlers after the client has connected (or rely on the client's connect-on-demand path) and retry once the server is up.","Catch this error and surface a clear message that progress reporting is unavailable rather than crashing the flow — progress is optional telemetry."],"exampleFix":"// before: name mismatch\nawait mcp.progress.onUpdate('fs', handler); // server configured as 'filesystem'\n// after\nawait mcp.progress.onUpdate('filesystem', handler);","handlingStrategy":"try-catch","validationCode":"// Confirm the server key exists in your config before registering\nconst configured = Object.keys(serversConfig); // same object passed to MCPClient\nif (!configured.includes('filesystem')) throw new Error('server not configured: filesystem');","typeGuard":"function isProgressHandlerError(e: unknown): e is MastraError {\n  return e instanceof MastraError && e.id === 'MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED';\n}","tryCatchPattern":"try {\n  await mcp.progress.onUpdate(serverName, handler);\n} catch (e) {\n  if (isProgressHandlerError(e)) {\n    logger.warn(`progress reporting unavailable for ${e.details.serverName}`, e);\n    return; // degrade: continue without progress notifications\n  }\n  throw e;\n}","preventionTips":["Derive server names programmatically from the servers config keys to avoid typos.","Register handlers at client setup, after verifying the server connects.","Pre-warm the connection (getToolsets/tools) before attaching handlers.","Treat progress reporting as optional; never let its failure crash the main flow."],"tags":["mcp","progress","event-handler","server-not-found"],"backgroundTag":"mcp-server-not-connected","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}