ruvnet/ruflo · error · Error

WG mesh layer not initialized (set config.wgMesh = true and

Error message

WG mesh layer not initialized (set config.wgMesh = true and inject WgMeshService)

What it means

The WireGuard-mesh guard in the federation MCP tools: requireWgMesh() throws when the WgMeshService getter returns null, meaning the host neither enabled config.wgMesh nor injected a WgMeshService. The message embeds the exact remedy; it fires only for WG-mesh-specific tools while the base federation layer works without it.

Source

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

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' },
          endpoint: { type: 'string', description: 'WebSocket or HTTP endpoint for this node' },
          agentTypes: { type: 'array', description: 'Supported agent types', items: { type: 'string' } },
        },
        required: ['endpoint'],
      },

View on GitHub (pinned to fa13ee4ad6)

Solutions

Set config.wgMesh = true in the agent-federation plugin config
Inject a real WgMeshService instance so the mesh getter resolves it instead of the default null getter
Restart or reload the plugin so the MCP tools are created with the wired getter

Example fix

// before
const config = { nodeId: 'node-a' }; // wgMesh not set -> requireWgMesh() throws

// after
const config = { nodeId: 'node-a', wgMesh: true };
// and inject the WgMeshService when wiring the plugin host

Defensive patterns

Strategy: validation

Validate before calling

const wgReady = pluginConfig['wgMesh'] === true && !!wgMeshService;
if (!wgReady) {
  throw new Error('WG mesh not configured: set config.wgMesh = true and inject WgMeshService before calling WG mesh tools');
}

Try / catch

try {
  await client.callTool('federation_wg_status', {});
} catch (e) {
  if (e instanceof Error && e.message.includes('WG mesh layer not initialized')) {
    // fix config + DI, reload the plugin, then retry; do not loop
  } else throw e;
}

Prevention

Declare wgMesh: true in config for every node using WG topology
Keep the wgMesh flag and the WgMeshService injection in the same wiring commit so they never diverge
Smoke-test one WG mesh tool immediately after startup

When it happens

Trigger: Calling WG-mesh federation MCP tools when the plugin config lacks wgMesh: true, or when the host wiring never passed a WgMeshService into createMcpTools (the getWgMesh parameter defaults to () => null).

Common situations: Running with default config (WG mesh is opt-in); upgrading to a version where the WG mesh became a separately injected service; custom plugin hosts that only wire the base coordinator.

Related errors

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