{"record":{"id":"a606074d76ec95b9","repo":"mastra-ai/mastra","slug":"mcp-client-read-resource-failed","errorCode":"MCP_CLIENT_READ_RESOURCE_FAILED","errorMessage":"MCP_CLIENT_READ_RESOURCE_FAILED","messagePattern":"MCP_CLIENT_READ_RESOURCE_FAILED","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/mcp/src/client/configuration.ts","lineNumber":385,"sourceCode":"       * Reads the content of a specific resource from a server.\n       *\n       * @param serverName - Name of the server to read from\n       * @param uri - URI of the resource to read\n       * @returns Promise resolving to the resource content\n       * @throws {MastraError} If reading the resource fails\n       *\n       * @example\n       * ```typescript\n       * const content = await mcp.resources.read('weatherServer', 'file://config.json');\n       * console.log(content.contents[0].text);\n       * ```\n       */\n      read: async (serverName: string, uri: string) => {\n        try {\n          const internalClient = await this.getConnectedClientForServer(serverName);\n          return internalClient.resources.read(uri);\n        } catch (error) {\n          throw new MastraError(\n            {\n              id: 'MCP_CLIENT_READ_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       * 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","sourceCodeStart":367,"sourceCodeEnd":403,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/mcp/src/client/configuration.ts#L367-L403","documentation":"Thrown when reading an MCP resource fails: MCPClient's resources.read(serverName, uri) connects to the named server and calls internalClient.resources.read(uri); any failure is wrapped in a MastraError with id MCP_CLIENT_READ_RESOURCE_FAILED (category THIRD_PARTY). The underlying cause (unknown server, connection failure, or the server rejecting the URI) is preserved as the wrapped error.","triggerScenarios":"Calling mcpClient.resources.read('myServer', 'file:///data/x.txt') when serverName is not configured, the server cannot be connected to, or the server rejects the read (unknown URI, permission denied, resource deleted, unsupported scheme).","commonSituations":"Typo in server name; malformed or wrong-scheme URI (http:// vs file:// vs custom scheme the server doesn't serve); resource removed after a server restart; server process failed to spawn.","solutions":["Validate the URI against the server's resource list (resources.list(serverName)) before reading, and check scheme/format.","Verify serverName matches the servers config exactly and that the server is running/connectable (check its logs, transport config).","Catch this error and retry once if the server was restarting; otherwise surface 'resource not available' to the user.","Fix the server-side cause reported by the wrapped error (permissions, missing file, unsupported scheme)."],"exampleFix":"// before\nconst res = await mcp.resources.read('docs', 'http://x/readme.md'); // server serves file:// URIs\n// after\nconst list = await mcp.resources.list('docs');\nconst res = await mcp.resources.read('docs', list.resources[0].uri); // valid server-provided URI","handlingStrategy":"validation","validationCode":"// Validate the URI against the server's resource list before reading\nconst { resources } = await mcp.resources.list(serverName);\nconst target = resources.find(r => r.uri === uri);\nif (!target) throw new Error(`resource not offered by ${serverName}: ${uri}`);","typeGuard":"function isReadResourceError(e: unknown): e is MastraError {\n  return e instanceof MastraError && e.id === 'MCP_CLIENT_READ_RESOURCE_FAILED';\n}","tryCatchPattern":"try {\n  return await mcp.resources.read(serverName, uri);\n} catch (e) {\n  if (isReadResourceError(e)) {\n    logger.warn(`resource read failed: ${e.details?.serverName} ${uri}`, e);\n    await sleep(retryDelay); // retry once if server was restarting\n    return await mcp.resources.read(serverName, uri);\n  }\n  throw e;\n}","preventionTips":["Always read URIs obtained from resources.list rather than hand-constructed ones.","Use the exact config key as serverName (store in constants).","Check the server process is alive before resource-heavy operations.","Handle URI schemes the server actually supports (file://, custom schemes)."],"tags":["mcp","resources","read","uri"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}