{"record":{"id":"481056fb9b9c77f7","repo":"ruvnet/ruflo","slug":"fetchagentcard-invalid-a2a-agent-card-from-sour","errorCode":null,"errorMessage":"fetchAgentCard: invalid A2A agent card from ${sourceUrl}: ${validation.errors.join('; ')}","messagePattern":"fetchAgentCard: invalid A2A agent card from (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/plugin-agent-federation/src/a2a/consume.ts","lineNumber":82,"sourceCode":"    }\n    text = await res.text();\n  } finally {\n    clearTimeout(timer);\n  }\n  if (text.length > maxBytes) {\n    throw new Error(`fetchAgentCard: card exceeds ${maxBytes} bytes`);\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(text);\n  } catch {\n    throw new Error(`fetchAgentCard: ${sourceUrl} did not return valid JSON`);\n  }\n\n  const validation = validateAgentCard(parsed);\n  if (!validation.valid) {\n    throw new Error(\n      `fetchAgentCard: invalid A2A agent card from ${sourceUrl}: ${validation.errors.join('; ')}`,\n    );\n  }\n  return { card: parsed as A2AAgentCard, sourceUrl };\n}\n\n/**\n * Fetch a remote Agent Card and register the peer in federation discovery.\n * The peer enters at TrustLevel.UNTRUSTED (see fromAgentCard) — the card is\n * self-asserted metadata, and trust is earned through the normal handshake.\n */\nexport async function consumeAgentCard(\n  discovery: DiscoveryService,\n  baseOrCardUrl: string,\n  options: FetchAgentCardOptions = {},\n): Promise<FederationNode> {\n  const { card, sourceUrl } = await fetchAgentCard(baseOrCardUrl, options);\n  const node = fromAgentCard(card, sourceUrl);","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/plugin-agent-federation/src/a2a/consume.ts#L64-L100","documentation":"The card parsed as JSON but failed validateAgentCard(): the A2A Agent Card structure is non-conforming. The message enumerates every validation failure, joined with ';', naming the exact fields that are missing or have wrong types. Nothing is registered with federation discovery when this throws.","triggerScenarios":"Card missing required fields (capabilities, skills, or other mandatory keys); Wrong types on endpoints or URL fields; A card built against a different A2A spec revision than this validator implements; A partially written card observed mid-redeploy on the peer","commonSituations":"Peers implementing draft vs. final A2A card schemas; hand-authored card JSON with typos in field names; card generators lagging the spec.","solutions":["Read each item in validation.errors — they name the exact non-conforming fields","Compare the peer's card against the A2A Agent Card spec this package validates","Fix the card producer and fetch again after the peer redeploys","If both sides are yours, add the exported validator to the producer's CI so bad cards never ship"],"exampleFix":"// before\nawait consumeAgentCard(url, federation);\n// after\ntry {\n  await consumeAgentCard(url, federation);\n} catch (e) {\n  for (const err of String(e).split('; ')) console.error('card issue:', err);\n}","handlingStrategy":"try-catch","validationCode":"// if you produce cards, validate before serving\nconst parsed = JSON.parse(cardText);\nconst v = validateAgentCard(parsed);\nif (!v.valid) throw new Error('refusing to serve invalid card: ' + v.errors.join('; '));","typeGuard":null,"tryCatchPattern":"try {\n  await consumeAgentCard(url, federation);\n} catch (e) {\n  const msg = String(e);\n  if (msg.includes('invalid A2A agent card')) {\n    const detail = msg.slice(msg.lastIndexOf(': ') + 2);\n    for (const err of detail.split('; ')) console.error('card issue:', err);\n    // do not register this peer; alert the peer operator\n  }\n  throw e;\n}","preventionTips":["Run the card validator in the producer's CI","Pin the A2A card schema revision across peers","Re-fetch after the peer redeploys rather than caching failures","Log each ';'-separated validation error separately for triage"],"tags":["validation","schema","a2a"],"backgroundTag":"schema-validation-failed","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}