{"record":{"id":"7275b2ef88ec73b5","repo":"mastra-ai/mastra","slug":"error-code","errorCode":"${error.code}","errorMessage":"${error.message} (remote JSON-RPC error, code ${error.code})","messagePattern":"(.+?) \\(remote JSON-RPC error, code (.+?)\\)","errorType":"exception","errorClass":"MastraA2AError","httpStatus":null,"severity":"error","filePath":"packages/core/src/a2a/a2a-agent.ts","lineNumber":183,"sourceCode":"    return;\n  }\n\n  const error = response.error;\n  if (error == null) {\n    return;\n  }\n\n  if (\n    typeof error !== 'object' ||\n    !('code' in error) ||\n    typeof error.code !== 'number' ||\n    !('message' in error) ||\n    typeof error.message !== 'string'\n  ) {\n    throw MastraA2AError.invalidAgentResponse('Remote A2A agent returned a malformed JSON-RPC error response.');\n  }\n\n  throw new MastraA2AError(error.code, error.message, 'data' in error ? error.data : undefined);\n}\n\nfunction splitNextEvent(buffer: string): { eventBlock?: string; rest: string } {\n  const normalizedBuffer = buffer.replace(/\\x1E/g, '\\n\\n');\n  const match = normalizedBuffer.match(/\\r?\\n\\r?\\n/);\n\n  if (!match || match.index === undefined) {\n    return { rest: normalizedBuffer };\n  }\n\n  return {\n    eventBlock: normalizedBuffer.slice(0, match.index),\n    rest: normalizedBuffer.slice(match.index + match[0].length),\n  };\n}\n\nfunction parseEventBlock(eventBlock: string): { done: true } | { event?: A2AStreamEventData } {\n  const trimmedBlock = eventBlock.trim();","sourceCodeStart":165,"sourceCodeEnd":201,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/a2a/a2a-agent.ts#L165-L201","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Verify the A2A agent base URL and that the remote server is running and reachable.","Check credentials/auth headers passed to the A2A agent client.","If the error references a task ID, confirm the task exists and hasn't expired on the remote."],"exampleFix":"// before\nconst agent = new Agent({ name: 'remote', ...new MastraA2AWrapper('http://localhost:4112/agents/wrong-name') });\n// after\nconst agent = new Agent({ name: 'remote', ...new MastraA2AWrapper('http://localhost:4112/agents/weather-agent') });","handlingStrategy":"try-catch","validationCode":"function isJsonRpcErrorPayload(res: unknown): res is { error: { code: number; message: string; data?: unknown } } {\n  const r = res as any;\n  return !!r && typeof r === 'object' && r.error && typeof r.error.code === 'number' && typeof r.error.message === 'string';\n}","typeGuard":"function isMastraA2AError(e: unknown): e is { code: number; message: string; data?: unknown } {\n  return e instanceof Error && 'code' in e && typeof (e as any).code === 'number';\n}","tryCatchPattern":"try {\n  const res = await a2aAgent.generate(input);\n} catch (err) {\n  if (err instanceof MastraA2AError) {\n    console.error(`Remote agent error ${err.code}: ${err.message}`, err.data);\n    if (err.code === -32601) throw new Error('A2A method not found — check the remote agent URL/name');\n    if ([401, 403].includes(err.code) || /auth/i.test(err.message)) throw new Error('A2A auth failed — check credentials');\n  }\n  throw err;\n}","preventionTips":["Health-check the remote A2A agent (URL + agent id) before relying on it in production.","Log err.data from MastraA2AError — it often carries the remote's diagnostic payload.","Renew/rotate remote credentials and verify auth headers on every deploy.","Map JSON-RPC codes (-32600/-32601/-32602/-32700, -32000) to concrete runbooks."],"tags":["a2a","network","json-rpc","remote-agent"],"backgroundTag":"remote-json-rpc-error","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}