ruvnet/ruflo · error · Error

Federation not initialized

Error message

Federation not initialized

What it means

Guard inside the agent-federation MCP tool factory: every federation tool except federation_init obtains its FederationCoordinator via requireCoordinator(), and if the coordinator getter still returns null (federation was never initialized on this node, or init failed) it throws this plain Error. It is a precondition/ordering error, not a network failure.

Source

Thrown at v3/@claude-flow/plugin-agent-federation/src/mcp-tools.ts:26

import { JCS_SIGNATURE_PROTOCOL } from './application/inbound-dispatcher.js';
import { FEDERATION_PLUGIN_VERSION } from './version.js';

type CoordinatorGetter = () => FederationCoordinator | null;
type ContextGetter = () => PluginContext | null;
type WgMeshGetter = () => WgMeshService | null;

function textResult(text: string, isError = false) {
  return { content: [{ type: 'text' as const, text }], isError };
}

export function createMcpTools(
  getCoordinator: CoordinatorGetter,
  getContext: ContextGetter,
  getWgMesh: WgMeshGetter = () => null,
): MCPToolDefinition[] {
  function requireCoordinator(): FederationCoordinator {
    const c = getCoordinator();
    if (!c) throw new Error('Federation not initialized');
    return c;
  }
  function requireWgMesh(): WgMeshService {
    const w = getWgMesh();
    if (!w) throw new Error('WG mesh layer not initialized (set config.wgMesh = true and inject WgMeshService)');
    return w;
  }

  return [
    {
      name: 'federation_init',
      description: 'Initialize federation on this node with a manifest and begin discovery',
      pluginName: '@claude-flow/plugin-agent-federation',
      version: FEDERATION_PLUGIN_VERSION,
      inputSchema: {
        type: 'object',
        properties: {
          nodeId: { type: 'string', description: 'Unique node identifier' },

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Call the federation_init tool with a valid manifest and confirm it succeeds before any other federation tool
2. If init already ran, inspect plugin startup logs for a failed FederationCoordinator construction and fix the root cause
3. In tests or custom hosts, wire the getter to an initialized coordinator instead of a null-returning stub

Example fix

// before
await client.callTool('federation_send', { targetNodeId, envelope }); // throws 'Federation not initialized'

// after
await client.callTool('federation_init', { manifest });
await client.callTool('federation_send', { targetNodeId, envelope });

const init = await client.callTool('federation_init', { manifest });
if (init.isError) throw new Error('federation bootstrap failed; do not call federation tools');
// only now enable dependent federation tool calls

try {
  await client.callTool('federation_peers', {});
} catch (e) {
  if (e instanceof Error && e.message === 'Federation not initialized') {
    await client.callTool('federation_init', { manifest });
    await client.callTool('federation_peers', {}); // retry once
  } else throw e;
}

When it happens

Trigger: Invoking any federation MCP tool other than federation_init (peer listing, envelope send, etc.) before a successful federation_init call, or after the coordinator failed to construct or was shut down so getCoordinator() yields null.

Common situations: Automation scripts or agent flows that call federation tools first; a failed federation_init (bad manifest, key-file write error) that leaves the coordinator unset; unit tests that build the tools with a () => null getter.

Related errors

• WG mesh layer not initialized (set config.wgMesh = true and
• IoT Cognitum not initialized
• unknown game "${key}". Known: ${Object.keys(GAMES).join(', '
• unknown strategy "${name}". Available: ${roster.map((r) => r
• localCompute: no adapter for graphId=${input.graphId}

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