ruvnet/ruflo · error

A2A agent card endpoint unavailable (${err instanceof Error

Error message

A2A agent card endpoint unavailable (${err instanceof Error ? err.message : err}); federation continues without the A2A discovery surface

What it means

Log warning in initialize: starting the A2A well-known agent-card HTTP server failed (port busy or bind error); federation continues to function but without the HTTP discovery surface advertising its card.

Source

Thrown at v3/@claude-flow/plugin-agent-federation/src/plugin.ts:526

                  'websocket',
                  'http',
                  ...(signatureMode === 'legacy' ? [] : [JCS_SIGNATURE_PROTOCOL]),
                ],
                complianceModes: complianceMode === 'none' ? [] : [complianceMode],
              },
              version: this.version,
              signature: '',
              timestamp: new Date().toISOString(),
            };
            return toAgentCard(manifest);
          },
          port: a2aPort,
          host: (config['a2aCardHost'] as string | undefined) ?? '127.0.0.1',
          allowNonLoopback: config['a2aCardAllowNonLoopback'] === true,
        });
        context.logger.info(`A2A agent card served at ${this.agentCardServer.url}`);
      } catch (err) {
        context.logger.warn(
          `A2A agent card endpoint unavailable (${err instanceof Error ? err.message : err}); ` +
            'federation continues without the A2A discovery surface',
        );
        this.agentCardServer = null;
      }
    }

    context.logger.info('Agent Federation plugin initialized');
  }

  async shutdown(): Promise<void> {
    if (this.agentCardServer) {
      try {
        await this.agentCardServer.close();
      } catch (err) {
        this.context?.logger.warn(
          `A2A agent card server close error: ${err instanceof Error ? err.message : err}`,
        );

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Check why the A2A agent card endpoint failed to bind (port in use, permissions); federation works without it but A2A discovery is unavailable.

When it happens

Trigger: Thrown at v3/@claude-flow/plugin-agent-federation/src/plugin.ts:526 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/45f8cd97c7c37247. Report an issue: GitHub.