{"record":{"id":"ec568be1863e7983","repo":"ruvnet/ruflo","slug":"federation-not-initialized","errorCode":null,"errorMessage":"Federation not initialized","messagePattern":"Federation not initialized","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/plugin-agent-federation/src/mcp-tools.ts","lineNumber":26,"sourceCode":"import { JCS_SIGNATURE_PROTOCOL } from './application/inbound-dispatcher.js';\nimport { FEDERATION_PLUGIN_VERSION } from './version.js';\n\ntype CoordinatorGetter = () => FederationCoordinator | null;\ntype ContextGetter = () => PluginContext | null;\ntype WgMeshGetter = () => WgMeshService | null;\n\nfunction textResult(text: string, isError = false) {\n  return { content: [{ type: 'text' as const, text }], isError };\n}\n\nexport function createMcpTools(\n  getCoordinator: CoordinatorGetter,\n  getContext: ContextGetter,\n  getWgMesh: WgMeshGetter = () => null,\n): MCPToolDefinition[] {\n  function requireCoordinator(): FederationCoordinator {\n    const c = getCoordinator();\n    if (!c) throw new Error('Federation not initialized');\n    return c;\n  }\n  function requireWgMesh(): WgMeshService {\n    const w = getWgMesh();\n    if (!w) throw new Error('WG mesh layer not initialized (set config.wgMesh = true and inject WgMeshService)');\n    return w;\n  }\n\n  return [\n    {\n      name: 'federation_init',\n      description: 'Initialize federation on this node with a manifest and begin discovery',\n      pluginName: '@claude-flow/plugin-agent-federation',\n      version: FEDERATION_PLUGIN_VERSION,\n      inputSchema: {\n        type: 'object',\n        properties: {\n          nodeId: { type: 'string', description: 'Unique node identifier' },","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/plugin-agent-federation/src/mcp-tools.ts#L8-L44","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Call the federation_init tool with a valid manifest and confirm it succeeds before any other federation tool","If init already ran, inspect plugin startup logs for a failed FederationCoordinator construction and fix the root cause","In tests or custom hosts, wire the getter to an initialized coordinator instead of a null-returning stub"],"exampleFix":"// before\nawait client.callTool('federation_send', { targetNodeId, envelope }); // throws 'Federation not initialized'\n\n// after\nawait client.callTool('federation_init', { manifest });\nawait client.callTool('federation_send', { targetNodeId, envelope });","handlingStrategy":"validation","validationCode":"const init = await client.callTool('federation_init', { manifest });\nif (init.isError) throw new Error('federation bootstrap failed; do not call federation tools');\n// only now enable dependent federation tool calls","typeGuard":null,"tryCatchPattern":"try {\n  await client.callTool('federation_peers', {});\n} catch (e) {\n  if (e instanceof Error && e.message === 'Federation not initialized') {\n    await client.callTool('federation_init', { manifest });\n    await client.callTool('federation_peers', {}); // retry once\n  } else throw e;\n}","preventionTips":["Run federation_init as the first step of every federation session and abort the session if it errors","Gate dependent federation tool calls behind a successful-init flag","In tests, inject a getter that returns a real initialized coordinator"],"tags":["federation","mcp","initialization-order","claude-flow"],"backgroundTag":"service-not-initialized","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}