{"record":{"id":"390cf37292279bdc","repo":"mastra-ai/mastra","slug":"mcp-client-subscribe-resource-failed","errorCode":"MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED","errorMessage":"MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED","messagePattern":"MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/configuration.ts","lineNumber":417,"sourceCode":"      /**\n       * Subscribes to updates for a specific resource on a server.\n       *\n       * @param serverName - Name of the server\n       * @param uri - URI of the resource to subscribe to\n       * @returns Promise resolving when subscription is established\n       * @throws {MastraError} If subscription fails\n       *\n       * @example\n       * ```typescript\n       * await mcp.resources.subscribe('weatherServer', 'file://config.json');\n       * ```\n       */\n      subscribe: async (serverName: string, uri: string) => {\n        try {\n          const internalClient = await this.getConnectedClientForServer(serverName);\n          return internalClient.resources.subscribe(uri);\n        } catch (error) {\n          throw new MastraError(\n            {\n              id: 'MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED',\n              domain: ErrorDomain.MCP,\n              category: ErrorCategory.THIRD_PARTY,\n              details: {\n                serverName,\n                uri,\n              },\n            },\n            error,\n          );\n        }\n      },\n      /**\n       * Unsubscribes from updates for a specific resource on a server.\n       *\n       * @param serverName - Name of the server\n       * @param uri - URI of the resource to unsubscribe from","sourceCodeStart":399,"sourceCodeEnd":435,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/configuration.ts#L399-L435","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Verify the resource URI exists via resources.list(serverName) before subscribing.","Confirm the server advertises the resources/subscribe capability; if not, poll with resources.read instead of subscribing.","Check serverName matches the config and the server is connected; fix transport errors first.","Catch and degrade gracefully: fall back to periodic re-reads when subscribe fails."],"exampleFix":"// before\nawait mcp.resources.subscribe('logs', 'file:///var/log/app.log'); // server lacks subscribe capability\n// after: fallback polling\ntry {\n  await mcp.resources.subscribe('logs', 'file:///var/log/app.log');\n} catch {\n  setInterval(() => mcp.resources.read('logs', 'file:///var/log/app.log'), 10_000);\n}","handlingStrategy":"fallback","validationCode":"const { resources } = await mcp.resources.list(serverName);\nif (!resources.some(r => r.uri === uri)) throw new Error(`cannot subscribe: unknown resource ${uri}`);","typeGuard":"function isSubscribeError(e: unknown): e is MastraError {\n  return e instanceof MastraError && e.id === 'MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED';\n}","tryCatchPattern":"try {\n  await mcp.resources.subscribe(serverName, uri);\n  activeSubs.add(uri);\n} catch (e) {\n  if (isSubscribeError(e)) {\n    logger.warn(`subscribe unsupported/failed for ${uri}; falling back to polling`, e);\n    const t = setInterval(() => mcp.resources.read(serverName, uri).catch(noop), 10_000);\n    pollers.set(uri, t); // polling fallback\n  } else throw e;\n}","preventionTips":["Confirm the server supports the resources/subscribe capability before relying on subscriptions.","Only subscribe to URIs returned by resources.list.","Track active subscriptions to make subscribe/unsubscribe idempotent.","Fall back to polling reads when subscribe fails rather than failing the feature."],"tags":["mcp","resources","subscribe","capability"],"backgroundTag":"unsupported-mcp-capability","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}