mastra-ai/mastra · error · MastraClientError

A2A stream error - ${JSON.stringify(parsed.error)}

Error message

A2A stream error - ${JSON.stringify(parsed.error)}

What it means

After successfully parsing an A2A stream event block, parseEventBlock checks for an 'error' field in the JSON object. If present, it throws MastraClientError with HTTP status 200 (since the transport itself succeeded) and a message embedding the JSON-stringified error payload from the remote agent.

Source

Thrown at client-sdks/client-js/src/utils/process-a2a-stream.ts:49

  const dataLines = lines.filter(line => line.startsWith('data:')).map(line => line.slice(5).trimStart());

  const payload = dataLines.length > 0 ? dataLines.join('\n') : trimmedBlock;

  if (!payload || payload === '[DONE]') {
    return { done: true };
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(payload);
  } catch (error) {
    throw new Error(
      `Failed to parse A2A stream event: ${error instanceof Error ? error.message : 'unknown parse error'}`,
    );
  }

  if (parsed && typeof parsed === 'object' && 'error' in parsed && parsed.error) {
    throw new MastraClientError(200, 'OK', `A2A stream error - ${JSON.stringify(parsed.error)}`, parsed.error);
  }

  if (parsed && typeof parsed === 'object' && 'result' in parsed) {
    return { event: parsed.result as T };
  }

  return { event: parsed as T };
}

export async function* processA2AStream<T = A2AStreamEventData>(
  stream: globalThis.ReadableStream<Uint8Array>,
): AsyncGenerator<T, void, undefined> {
  const reader = stream.getReader();
  const decoder = new TextDecoder();
  let buffer = '';

  try {
    while (true) {

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Read the error detail from MastraClientError (the parsed.error is attached as the error context/domain) to identify the remote cause.
  2. Verify A2A authentication/credentials sent to the remote agent are valid.
  3. Validate request params (message, skill id, task id) against the remote agent's Agent Card requirements.
  4. Check the remote agent service health/logs; the failure originated server-side.
  5. Ensure client and server A2A protocol versions match (Agent Card protocol version vs client).

Example fix

// before
const events = await client.getA2ATools(...); // surfaces MastraClientError: A2A stream error - {"code":-32601,...}
// after
catch (e) {
  if (e instanceof MastraClientError) console.error('A2A remote error:', e.error);
  // fix request per remote error code, then retry
}
Defensive patterns

Strategy: try-catch

Validate before calling

// inspect events for embedded errors before consuming result
event.payload && typeof event.payload === 'object' && 'error' in event.payload
  ? reject(new Error('Remote A2A error: ' + JSON.stringify(event.payload.error)))
  : accept(event.payload);

Type guard

function isA2AErrorEvent(v: unknown): v is { error: unknown } {
  return typeof v === 'object' && v !== null && 'error' in v && (v as any).error;
}

Try / catch

try {
  for await (const ev of a2aStream) handle(ev);
} catch (e) {
  if (e instanceof MastraClientError && e.message.startsWith('A2A stream error')) {
    console.error('Remote agent failed:', e.error ?? e.message);
    // surface to user or retry with corrected request
  } else throw e;
}

Prevention

When it happens

Trigger: Any A2A stream event emitted by the remote agent that contains a truthy "error" property — e.g. the agent reports a task failure, unsupported operation, authentication failure, or internal exception serialized as { error: {...} } in the stream.

Common situations: Remote A2A agent rejecting the request (bad API key, missing skill), agent-side runtime exception during task execution, version mismatch where the server sends error shapes the client surfaces verbatim, or sending an invalid payload/params the agent cannot process.

Related errors

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