ruvnet/ruflo · error

agent_card_not_ready

Error message

agent_card_not_ready

What it means

JSON error body returned by the A2A agent-card server when the card provider callback cannot produce a manifest yet (e.g. plugin still initializing or manifest build failed), so the server cannot serve agent-card JSON for the well-known path.

Source

Thrown at v3/@claude-flow/plugin-agent-federation/src/a2a/well-known.ts:83

      `A2A agent-card server: refusing non-loopback bind ${host} without allowNonLoopback: true (ADR-166)`,
    ));
  }

  const server: Server = createServer((req, res) => {
    const reqPath = (req.url ?? '').split('?')[0];
    if (reqPath !== path) {
      res.writeHead(404, { 'content-type': 'application/json' });
      res.end(JSON.stringify({ error: 'not_found', agentCardPath: path }));
      return;
    }
    if (req.method !== 'GET' && req.method !== 'HEAD') {
      res.writeHead(405, { allow: 'GET, HEAD', 'content-type': 'application/json' });
      res.end(JSON.stringify({ error: 'method_not_allowed' }));
      return;
    }
    const card = options.getCard();
    if (!card) {
      res.writeHead(503, { 'content-type': 'application/json', 'retry-after': '5' });
      res.end(JSON.stringify({ error: 'agent_card_not_ready' }));
      return;
    }
    const body = JSON.stringify(card, null, 2);
    const etag = `"${createHash('sha256').update(body).digest('hex').slice(0, 32)}"`;
    if (req.headers['if-none-match'] === etag) {
      res.writeHead(304, { etag });
      res.end();
      return;
    }
    res.writeHead(200, {
      'content-type': 'application/json',
      'cache-control': `public, max-age=${maxAge}`,
      etag,
    });
    res.end(req.method === 'HEAD' ? undefined : body);
  });

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Wait for the agent card to finish initializing before requesting the well-known endpoint; retry with backoff.

When it happens

Trigger: Thrown at v3/@claude-flow/plugin-agent-federation/src/a2a/well-known.ts:83 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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