mastra-ai/mastra · error · MastraError

MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED

MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED

Error message

MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED

What it means

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.

Source

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

       * @param serverName - Name of the server to monitor
       * @param handler - Callback function invoked when prompts are added/removed/modified
       * @returns Promise resolving when handler is registered
       * @throws {MastraError} If setting up the handler fails
       *
       * @example
       * ```typescript
       * await mcp.prompts.onListChanged('weatherServer', async () => {
       *   console.log('Prompt list changed, re-fetching...');
       *   const prompts = await mcp.prompts.list();
       * });
       * ```
       */
      onListChanged: async (serverName: string, handler: () => void) => {
        try {
          const internalClient = await this.getConnectedClientForServer(serverName);
          return internalClient.prompts.onListChanged(handler);
        } catch (error) {
          throw new MastraError(
            {
              id: 'MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED',
              domain: ErrorDomain.MCP,
              category: ErrorCategory.THIRD_PARTY,
              details: {
                serverName,
              },
            },
            error,
          );
        }
      },
    };
  }

  /**
   * Provides access to tool-related notification operations across all configured servers.
   *

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure the server is configured and a connection is established before registering the handler.
2. Check the serverName spelling against your MCPClient configuration.
3. Await client connection/initialization (or use getConnectedClientForServer semantics) prior to subscription.
4. Retry the subscription after reconnecting if the server was temporarily down.

Example fix

// before
client.prompts.onListChanged('myserver', () => refresh());
// after
await client.getConnectedClientForServer('myserver'); // ensure connection first
client.prompts.onListChanged('myserver', () => refresh());

if (!Object.keys(configuredServers).includes(serverName)) throw new Error(`unknown server ${serverName}`);
await client.getConnectedClientForServer(serverName); // throws early if unreachable

try {
  client.prompts.onListChanged(serverName, handler);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED') {
    scheduleRetry(() => client.prompts.onListChanged(serverName, handler));
  } else throw e;
}

When it happens

Trigger: Calling mcpClient.prompts.onListChanged(serverName, handler) when getConnectedClientForServer(serverName) throws (unknown server name, connection not established, server unreachable).

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

Related errors

• MCP_CLIENT_ON_LIST_CHANGED_TOOLS_FAILED
• Failed to fetch prompts from server ${this.client.name}: ${e
• Could not connect to server with any available HTTP transpor
• MCP_CLIENT_GET_PROMPT_FAILED
• Failed to load prompts

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