FederationCoordinator is not initialized. Call initialize()

Error message

FederationCoordinator is not initialized. Call initialize() first.

What it means

Lifecycle guard on FederationCoordinator: operational methods call ensureInitialized(), which throws this unless initialize() has completed. The guard exists because transport, session tables, and policy state are only usable after initialization, and calling earlier would operate on half-built state.

Source

Thrown at v3/@claude-flow/plugin-agent-federation/src/application/federation-coordinator.ts:686

      targetNodeId: node.nodeId,
      trustLevel: session.trustLevel,
    });

    return session;
  }

  private findSessionByNodeId(nodeId: string): FederationSession | undefined {
    for (const session of this.sessions.values()) {
      if (session.remoteNodeId === nodeId && session.active) {
        return session;
      }
    }
    return undefined;
  }

  private ensureInitialized(): void {
    if (!this.initialized) {
      throw new Error('FederationCoordinator is not initialized. Call initialize() first.');
    }
  }
}

View on GitHub (pinned to fa13ee4ad6)

Solutions

await coordinator.initialize() — and handle its rejection — before any other call
Gate all uses behind the initialization promise (store it and await it at each entry point)
If initialize() failed, stop: log and surface the failure instead of continuing to use the coordinator
After shutdown(), create a new coordinator rather than reusing the instance

Example fix

// before
const c = new FederationCoordinator(cfg);
c.sendMessage(msg); // throws
// after
const c = new FederationCoordinator(cfg);
await c.initialize();
c.sendMessage(msg);

Defensive patterns

Strategy: validation

Validate before calling

const coordinator = new FederationCoordinator(cfg);
const ready = coordinator.initialize().catch(e => {
  log.error('federation init failed', e);
  throw e;
});
// gate every subsequent use
await ready;
coordinator.sendMessage(msg);

Try / catch

try {
  coordinator.sendMessage(msg);
} catch (e) {
  if (String(e).includes('not initialized')) {
    await coordinator.initialize();
    coordinator.sendMessage(msg); // retry once after init
  } else {
    throw e;
  }
}

Prevention

Create a single startup path that awaits initialize() before serving traffic
Store the init promise and await it at every entry point
Treat initialize() rejection as fatal — do not continue using the coordinator
Re-create the coordinator after shutdown instead of reusing it

When it happens

Trigger: Calling send/connect/claim operations before awaiting initialize(); initialize() rejected but the caller swallowed the error and continued; using a coordinator after shutdown() with the initialized flag cleared.

Common situations: Fire-and-forget startup where a message send races the init promise; DI wiring that lazily constructs but eagerly calls; catch blocks that log init failures without halting the flow.

Related errors

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