ruvnet/ruflo · error

fetchAgentCard: invalid A2A agent card from ${sourceUrl}: ${

Error message

fetchAgentCard: invalid A2A agent card from ${sourceUrl}: ${validation.errors.join('; ')}

What it means

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.

Source

Thrown at v3/@claude-flow/plugin-agent-federation/src/a2a/consume.ts:82

    }
    text = await res.text();
  } finally {
    clearTimeout(timer);
  }
  if (text.length > maxBytes) {
    throw new Error(`fetchAgentCard: card exceeds ${maxBytes} bytes`);
  }

  let parsed: unknown;
  try {
    parsed = JSON.parse(text);
  } catch {
    throw new Error(`fetchAgentCard: ${sourceUrl} did not return valid JSON`);
  }

  const validation = validateAgentCard(parsed);
  if (!validation.valid) {
    throw new Error(
      `fetchAgentCard: invalid A2A agent card from ${sourceUrl}: ${validation.errors.join('; ')}`,
    );
  }
  return { card: parsed as A2AAgentCard, sourceUrl };
}

/**
 * Fetch a remote Agent Card and register the peer in federation discovery.
 * The peer enters at TrustLevel.UNTRUSTED (see fromAgentCard) — the card is
 * self-asserted metadata, and trust is earned through the normal handshake.
 */
export async function consumeAgentCard(
  discovery: DiscoveryService,
  baseOrCardUrl: string,
  options: FetchAgentCardOptions = {},
): Promise<FederationNode> {
  const { card, sourceUrl } = await fetchAgentCard(baseOrCardUrl, options);
  const node = fromAgentCard(card, sourceUrl);

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Read each item in validation.errors — they name the exact non-conforming fields
2. Compare the peer's card against the A2A Agent Card spec this package validates
3. Fix the card producer and fetch again after the peer redeploys
4. If both sides are yours, add the exported validator to the producer's CI so bad cards never ship

Example fix

// before
await consumeAgentCard(url, federation);
// after
try {
  await consumeAgentCard(url, federation);
} catch (e) {
  for (const err of String(e).split('; ')) console.error('card issue:', err);
}

// if you produce cards, validate before serving
const parsed = JSON.parse(cardText);
const v = validateAgentCard(parsed);
if (!v.valid) throw new Error('refusing to serve invalid card: ' + v.errors.join('; '));

try {
  await consumeAgentCard(url, federation);
} catch (e) {
  const msg = String(e);
  if (msg.includes('invalid A2A agent card')) {
    const detail = msg.slice(msg.lastIndexOf(': ') + 2);
    for (const err of detail.split('; ')) console.error('card issue:', err);
    // do not register this peer; alert the peer operator
  }
  throw e;
}

When it happens

Trigger: 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

Common situations: Peers implementing draft vs. final A2A card schemas; hand-authored card JSON with typos in field names; card generators lagging the spec.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• field "${key}" must be a non-empty string
• field "${key}" must be a finite number
• field "${key}" must be a boolean
• field "${key}" must be an array
• agent must be an object

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/481056fb9b9c77f7. Report an issue: GitHub.