mastra-ai/mastra · error · MastraA2AError

${error.code}

${error.code}

Error message

${error.message} (remote JSON-RPC error, code ${error.code})

What it means

When a remote A2A agent replies with a JSON-RPC response containing an error object, Mastra rethrows it as a MastraA2AError carrying the remote code, message, and optional data. The message template is "<remote message> (remote JSON-RPC error, code <code>)". This is the remote agent's failure, propagated to your local call site (parseEventBlock/unwrapA2AResult during generate/stream).

Source

Thrown at packages/core/src/a2a/a2a-agent.ts:183

    return;
  }

  const error = response.error;
  if (error == null) {
    return;
  }

  if (
    typeof error !== 'object' ||
    !('code' in error) ||
    typeof error.code !== 'number' ||
    !('message' in error) ||
    typeof error.message !== 'string'
  ) {
    throw MastraA2AError.invalidAgentResponse('Remote A2A agent returned a malformed JSON-RPC error response.');
  }

  throw new MastraA2AError(error.code, error.message, 'data' in error ? error.data : undefined);
}

function splitNextEvent(buffer: string): { eventBlock?: string; rest: string } {
  const normalizedBuffer = buffer.replace(/\x1E/g, '\n\n');
  const match = normalizedBuffer.match(/\r?\n\r?\n/);

  if (!match || match.index === undefined) {
    return { rest: normalizedBuffer };
  }

  return {
    eventBlock: normalizedBuffer.slice(0, match.index),
    rest: normalizedBuffer.slice(match.index + match[0].length),
  };
}

function parseEventBlock(eventBlock: string): { done: true } | { event?: A2AStreamEventData } {
  const trimmedBlock = eventBlock.trim();

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the remote message and JSON-RPC code in the error; map standard codes (-32601 method not found, -32602 invalid params, -32700 parse error, -32000 server error) to the fix.
2. Verify the A2A agent base URL and that the remote server is running and reachable.
3. Check credentials/auth headers passed to the A2A agent client.
4. If the error references a task ID, confirm the task exists and hasn't expired on the remote.

Example fix

// before
const agent = new Agent({ name: 'remote', ...new MastraA2AWrapper('http://localhost:4112/agents/wrong-name') });
// after
const agent = new Agent({ name: 'remote', ...new MastraA2AWrapper('http://localhost:4112/agents/weather-agent') });

function isJsonRpcErrorPayload(res: unknown): res is { error: { code: number; message: string; data?: unknown } } {
  const r = res as any;
  return !!r && typeof r === 'object' && r.error && typeof r.error.code === 'number' && typeof r.error.message === 'string';
}

function isMastraA2AError(e: unknown): e is { code: number; message: string; data?: unknown } {
  return e instanceof Error && 'code' in e && typeof (e as any).code === 'number';
}

try {
  const res = await a2aAgent.generate(input);
} catch (err) {
  if (err instanceof MastraA2AError) {
    console.error(`Remote agent error ${err.code}: ${err.message}`, err.data);
    if (err.code === -32601) throw new Error('A2A method not found — check the remote agent URL/name');
    if ([401, 403].includes(err.code) || /auth/i.test(err.message)) throw new Error('A2A auth failed — check credentials');
  }
  throw err;
}

When it happens

Trigger: Calling methods on a Mastra A2A client agent whose remote agent returns a JSON-RPC error: agent unavailable, unsupported method, invalid params, task not found, auth failure, or the remote hit an internal error while generating/streaming.

Common situations: Remote agent URL wrong (404/route not found), missing or expired credentials for the remote agent, remote agent task expired/canceled, or the remote agent's model/infra failing mid-request.

Related errors

• A2A JSON-RPC response did not include a result
• Push notification failed with status ${response.status} ${re
• Token exchange failed: ${error}
• Failed to fetch user info from Auth0
• Token exchange failed: ${error}

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