mastra-ai/mastra · error · MastraError

MCP_CLIENT_GET_PROMPT_FAILED

MCP_CLIENT_GET_PROMPT_FAILED

Error message

MCP_CLIENT_GET_PROMPT_FAILED

What it means

MastraError wrapping any failure that occurs while fetching a prompt (prompts.get) from an MCP server via MCPClient's prompts API. The library first resolves a connected internal client for the named server, then delegates to internalClient.prompts.get; any error in connection or the remote get call is re-thrown with the serverName, prompt name, and args attached as details. Category THIRD_PARTY because the root cause is usually on the MCP server or connection layer.

Source

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

       * @returns Promise resolving to the prompt result with messages
       * @throws {MastraError} If fetching the prompt fails
       *
       * @example
       * ```typescript
       * const prompt = await mcp.prompts.get({
       *   serverName: 'weatherServer',
       *   name: 'forecast',
       *   args: { city: 'London' },
       * });
       * console.log(prompt.messages);
       * ```
       */
      get: async ({ serverName, name, args }: { serverName: string; name: string; args?: Record<string, any> }) => {
        try {
          const internalClient = await this.getConnectedClientForServer(serverName);
          return internalClient.prompts.get({ name, args });
        } catch (error) {
          throw new MastraError(
            {
              id: 'MCP_CLIENT_GET_PROMPT_FAILED',
              domain: ErrorDomain.MCP,
              category: ErrorCategory.THIRD_PARTY,
              details: {
                serverName,
                name,
              },
            },
            error,
          );
        }
      },
      /**
       * Sets a notification handler for when the prompt list changes on a server.
       *
       * @param serverName - Name of the server to monitor
       * @param handler - Callback function invoked when prompts are added/removed/modified

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify serverName matches a configured server and that the server is reachable (check its health/logs).
2. Confirm the prompt name exists via prompts.list on the same server.
3. Validate args against the prompt's declared arguments schema.
4. Catch the MastraError and inspect its details (serverName, name) and the wrapped cause for the underlying transport error.

Example fix

// before
const prompt = await client.prompts.get({ serverName: 'prod-server', name: 'code-review' });
// after
const prompts = await client.prompts.list({ serverName: 'prod-server' });
if (!prompts.some(p => p.name === 'code-review')) throw new Error('prompt not found');
const prompt = await client.prompts.get({ serverName: 'prod-server', name: 'code-review', args: { language: 'ts' } });

const names = Object.keys(configuredServers);
if (!names.includes(serverName)) throw new Error(`unknown server ${serverName}`);
const available = await client.prompts.list({ serverName });
if (!available.some(p => p.name === name)) throw new Error(`prompt ${name} not on ${serverName}`);

function isMastraErrorWithDetails(e: unknown): e is MastraError & { details: { serverName: string } } {
  return e instanceof MastraError && typeof (e as any).details?.serverName === 'string';
}

try {
  const prompt = await client.prompts.get({ serverName, name, args });
} catch (e) {
  if (e instanceof MastraError && e.id === 'MCP_CLIENT_GET_PROMPT_FAILED') {
    console.error(`prompt ${e.details.name} failed on ${e.details.serverName}`, e.detail?.originalMessage);
  } else throw e;
}

When it happens

Trigger: Calling mcpClient.prompts.get({ serverName, name, args }) when the server is not yet connected/connection fails, or the server rejects the prompt request (unknown prompt name, invalid args, server-side error).

Common situations: Typo in serverName or prompt name; server was disconnected or crashed before the call; args not matching the prompt's argument schema; MCP server version not supporting prompts capability.

Related errors

• Failed to fetch prompts from server ${this.client.name}: ${e
• MCP_CLIENT_TOOL_EXECUTION_FAILED
• MCP_CLIENT_ON_LIST_CHANGED_PROMPT_FAILED
• Failed to load prompts
• Prompt not found: ${name}

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