ruvnet/ruflo · error

not_found

Error message

not_found

What it means

JSON error body returned by the A2A agent-card server when the request path does not match the configured well-known agent-card path (default /.well-known/agent.json); the body names the expected agentCardPath and the response is a 404.

Source

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

 *   other path       → 404
 */
export function startAgentCardServer(
  options: AgentCardServerOptions,
): Promise<AgentCardServerHandle> {
  const host = options.host ?? '127.0.0.1';
  const path = options.path ?? A2A_WELL_KNOWN_PATH;
  const maxAge = options.cacheMaxAgeSeconds ?? 300;

  if (!isLoopbackHost(host) && options.allowNonLoopback !== true) {
    return Promise.reject(new Error(
      `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 });

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Request a resource that exists; verify the path/identifier against the service's published endpoints.

When it happens

Trigger: Thrown at v3/@claude-flow/plugin-agent-federation/src/a2a/well-known.ts:72 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/0bc01313726398ea. Report an issue: GitHub.