ruvnet/ruflo · error

Max sessions ( ) reached

Error message

Max sessions (${this.config.maxSessions}) reached

What it means

Thrown by BrowserSwarmCoordinator.spawnAgent in @claude-flow/browser when the number of live browser services (this.services) has reached the configured maxSessions ceiling. Each spawned navigator/scraper/validator/tester/monitor role creates a real BrowserService session, and the coordinator enforces a hard cap before creating a new one. The default cap is 5 (createBrowserSwarm defaults maxSessions to 5).

Solutions

1. Terminate or shut down idle/finished sessions before spawning new ones so services.size drops below the cap
2. Pass a higher maxSessions in the BrowserSwarmConfig given to createBrowserSwarm (e.g. createBrowserSwarm({ maxSessions: 20 })) sized to the host's browser capacity
3. Call swarm.getStats() first and gate spawning on activeSessions < maxSessions instead of blind-spawning
4. Wrap spawnAgent in a retry-with-backoff that waits for other agents to finish when the workload is bursty

Example fix

// before
const swarm = createBrowserSwarm(); // maxSessions defaults to 5
for (const url of urls) {
  const agent = await swarm.spawnAgent('scraper'); // throws on 6th
}

// after
const swarm = createBrowserSwarm({ maxSessions: urls.length });
for (const url of urls) {
  const agent = await swarm.spawnAgent('scraper');
  // ...await agent work...
  await agent.shutdown(); // free the slot before next spawn
}

const stats = swarm.getStats(); // { activeSessions, maxSessions, topology }
if (stats.activeSessions >= stats.maxSessions) {
  throw new Error(`spawn would exceed cap; terminate a session or raise maxSessions (currently ${stats.maxSessions})`);
}
const agent = await swarm.spawnAgent('scraper');

try { await swarm.spawnAgent(role); } catch (e) { if (e instanceof Error && e.message.startsWith('Max sessions')) { /* terminate idle sessions or backoff */ } throw e; }

When it happens

Trigger: Calling swarm.spawnAgent(role) when services.size >= config.maxSessions, e.g. spawning a 6th agent with the default config, or repeatedly spawning testers/monitors without terminating prior sessions. Sessions removed only via shutdown/termination of individual services.

Common situations: Loops that spawn one browser per task/page without closing finished ones; raising parallelism (e.g. shard count) without scaling maxSessions; long-running swarms where crashed branches are never reaped so stale entries keep services.size at the cap.

Related errors

• Maximum agent limit ( ) reached
• Agent not found
• Agent at maximum concurrent task capacity
• Agent already exists
• "@agntcy/slim-bindings" is installed but does not export…

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

Appendix: source

Thrown at v3/@claude-flow/browser/src/application/browser-service.ts:488

// ============================================================================
// Browser Swarm Coordinator
// ============================================================================

export class BrowserSwarmCoordinator {
  private config: BrowserSwarmConfig;
  private services: Map<string, BrowserService> = new Map();
  private sharedData: Map<string, unknown> = new Map();

  constructor(config: BrowserSwarmConfig) {
    this.config = config;
  }

  /**
   * Spawn a new browser agent in the swarm
   */
  async spawnAgent(role: 'navigator' | 'scraper' | 'validator' | 'tester' | 'monitor'): Promise<BrowserService> {
    if (this.services.size >= this.config.maxSessions) {
      throw new Error(`Max sessions (${this.config.maxSessions}) reached`);
    }

    const sessionId = `${this.config.sessionPrefix}-${role}-${Date.now()}`;
    const service = new BrowserService({
      sessionId,
      role,
      capabilities: this.getCapabilitiesForRole(role),
      defaultTimeout: 30000,
      headless: true,
    });

    this.services.set(sessionId, service);
    return service;
  }

  /**
   * Get capabilities for a role
   */

View on GitHub (pinned to fa13ee4ad6)