mastra-ai/mastra · error · MastraError

MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED

MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED

Error message

MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED

What it means

Thrown when subscribing to resource-change notifications fails: MCPClient's resources.subscribe(serverName, uri) connects and calls internalClient.resources.subscribe(uri); any failure is wrapped in a MastraError with id MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED (category THIRD_PARTY). It indicates the server did not accept a subscription for that resource.

Source

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

      /**
       * Subscribes to updates for a specific resource on a server.
       *
       * @param serverName - Name of the server
       * @param uri - URI of the resource to subscribe to
       * @returns Promise resolving when subscription is established
       * @throws {MastraError} If subscription fails
       *
       * @example
       * ```typescript
       * await mcp.resources.subscribe('weatherServer', 'file://config.json');
       * ```
       */
      subscribe: async (serverName: string, uri: string) => {
        try {
          const internalClient = await this.getConnectedClientForServer(serverName);
          return internalClient.resources.subscribe(uri);
        } catch (error) {
          throw new MastraError(
            {
              id: 'MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED',
              domain: ErrorDomain.MCP,
              category: ErrorCategory.THIRD_PARTY,
              details: {
                serverName,
                uri,
              },
            },
            error,
          );
        }
      },
      /**
       * Unsubscribes from updates for a specific resource on a server.
       *
       * @param serverName - Name of the server
       * @param uri - URI of the resource to unsubscribe from

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the resource URI exists via resources.list(serverName) before subscribing.
2. Confirm the server advertises the resources/subscribe capability; if not, poll with resources.read instead of subscribing.
3. Check serverName matches the config and the server is connected; fix transport errors first.
4. Catch and degrade gracefully: fall back to periodic re-reads when subscribe fails.

Example fix

// before
await mcp.resources.subscribe('logs', 'file:///var/log/app.log'); // server lacks subscribe capability
// after: fallback polling
try {
  await mcp.resources.subscribe('logs', 'file:///var/log/app.log');
} catch {
  setInterval(() => mcp.resources.read('logs', 'file:///var/log/app.log'), 10_000);
}

const { resources } = await mcp.resources.list(serverName);
if (!resources.some(r => r.uri === uri)) throw new Error(`cannot subscribe: unknown resource ${uri}`);

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

try {
  await mcp.resources.subscribe(serverName, uri);
  activeSubs.add(uri);
} catch (e) {
  if (isSubscribeError(e)) {
    logger.warn(`subscribe unsupported/failed for ${uri}; falling back to polling`, e);
    const t = setInterval(() => mcp.resources.read(serverName, uri).catch(noop), 10_000);
    pollers.set(uri, t); // polling fallback
  } else throw e;
}

When it happens

Trigger: Calling mcpClient.resources.subscribe('myServer', uri) when the server is unknown/unconnectable, or the server rejects the subscribe for that URI (resource doesn't exist, server doesn't support resources/subscribe capability).

Common situations: Subscribing to a URI the server doesn't expose; server lacks the resources.subscribe MCP capability (common with minimal/community servers); server name typo; connection dropped before the subscribe call.

Related errors

• Failed to fetch resources from server ${this.client.name}: $
• Failed to fetch resource templates from server ${this.client
• Cannot register an elicitation handler after connecting unle
• MCP_CLIENT_READ_RESOURCE_FAILED
• MCP_CLIENT_UNSUBSCRIBE_RESOURCE_FAILED

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