mastra-ai/mastra · error · MastraError

MCP_CLIENT_READ_RESOURCE_FAILED

MCP_CLIENT_READ_RESOURCE_FAILED

Error message

MCP_CLIENT_READ_RESOURCE_FAILED

What it means

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.

Source

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

       * Reads the content of a specific resource from a server.
       *
       * @param serverName - Name of the server to read from
       * @param uri - URI of the resource to read
       * @returns Promise resolving to the resource content
       * @throws {MastraError} If reading the resource fails
       *
       * @example
       * ```typescript
       * const content = await mcp.resources.read('weatherServer', 'file://config.json');
       * console.log(content.contents[0].text);
       * ```
       */
      read: async (serverName: string, uri: string) => {
        try {
          const internalClient = await this.getConnectedClientForServer(serverName);
          return internalClient.resources.read(uri);
        } catch (error) {
          throw new MastraError(
            {
              id: 'MCP_CLIENT_READ_RESOURCE_FAILED',
              domain: ErrorDomain.MCP,
              category: ErrorCategory.THIRD_PARTY,
              details: {
                serverName,
                uri,
              },
            },
            error,
          );
        }
      },
      /**
       * 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

View on GitHub (pinned to 75dd419e61)

Solutions

1. Validate the URI against the server's resource list (resources.list(serverName)) before reading, and check scheme/format.
2. Verify serverName matches the servers config exactly and that the server is running/connectable (check its logs, transport config).
3. Catch this error and retry once if the server was restarting; otherwise surface 'resource not available' to the user.
4. Fix the server-side cause reported by the wrapped error (permissions, missing file, unsupported scheme).

Example fix

// before
const res = await mcp.resources.read('docs', 'http://x/readme.md'); // server serves file:// URIs
// after
const list = await mcp.resources.list('docs');
const res = await mcp.resources.read('docs', list.resources[0].uri); // valid server-provided URI

// Validate the URI against the server's resource list before reading
const { resources } = await mcp.resources.list(serverName);
const target = resources.find(r => r.uri === uri);
if (!target) throw new Error(`resource not offered by ${serverName}: ${uri}`);

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

try {
  return await mcp.resources.read(serverName, uri);
} catch (e) {
  if (isReadResourceError(e)) {
    logger.warn(`resource read failed: ${e.details?.serverName} ${uri}`, e);
    await sleep(retryDelay); // retry once if server was restarting
    return await mcp.resources.read(serverName, uri);
  }
  throw e;
}

When it happens

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

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

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Failed to fetch resources from server ${this.client.name}: $
• Failed to fetch resource templates from server ${this.client
• MCP_CLIENT_SUBSCRIBE_RESOURCE_FAILED
• MCP_CLIENT_UNSUBSCRIBE_RESOURCE_FAILED
• MCP_CLIENT_ON_UPDATED_RESOURCE_FAILED

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