mastra-ai/mastra · error · MastraError

MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED

MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED

Error message

MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED

What it means

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.

Source

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

   * await mcp.progress.onUpdate('serverName', (params) => {
   *   console.log(`Progress: ${params.progress}%`);
   *   console.log(`Status: ${params.message}`);
   *
   *   if (params.total) {
   *     console.log(`Completed ${params.progress} of ${params.total} items`);
   *   }
   * });
   * ```
   */
  public get progress() {
    this.addToInstanceCache();
    return {
      onUpdate: async (serverName: string, handler: (params: ProgressNotification['params']) => void) => {
        try {
          const internalClient = await this.getConnectedClientForServer(serverName);
          return internalClient.progress.onUpdate(handler);
        } catch (err) {
          throw new MastraError(
            {
              id: 'MCP_CLIENT_ON_UPDATE_PROGRESS_FAILED',
              domain: ErrorDomain.MCP,
              category: ErrorCategory.THIRD_PARTY,
              details: {
                serverName,
              },
            },
            err,
          );
        }
      },
    };
  }

  /**
   * Provides access to elicitation-related operations for interactive user input collection.
   *

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check serverName exactly matches a key in the MCPClient servers configuration (and that the client's serverName matches this.name on the internal client).
2. Ensure the server connects: run it manually/inspect its logs, verify command/args/url and env; fix the transport error first.
3. Register handlers after the client has connected (or rely on the client's connect-on-demand path) and retry once the server is up.
4. Catch this error and surface a clear message that progress reporting is unavailable rather than crashing the flow — progress is optional telemetry.

Example fix

// before: name mismatch
await mcp.progress.onUpdate('fs', handler); // server configured as 'filesystem'
// after
await mcp.progress.onUpdate('filesystem', handler);

// Confirm the server key exists in your config before registering
const configured = Object.keys(serversConfig); // same object passed to MCPClient
if (!configured.includes('filesystem')) throw new Error('server not configured: filesystem');

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

try {
  await mcp.progress.onUpdate(serverName, handler);
} catch (e) {
  if (isProgressHandlerError(e)) {
    logger.warn(`progress reporting unavailable for ${e.details.serverName}`, e);
    return; // degrade: continue without progress notifications
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• MCP_CLIENT_ON_REQUEST_ELICITATION_FAILED
• MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED
• MCP_CLIENT_ON_LIST_CHANGED_RESOURCE_FAILED
• No arguments provided
• Invalid arguments for firecrawl_scrape

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