{"record":{"id":"f35ec083b3e05d9c","repo":"ruvnet/ruflo","slug":"maximum-agents-this-config-maxagents-reached-f35ec0","errorCode":null,"errorMessage":"Maximum agents (${this.config.maxAgents}) reached","messagePattern":"Maximum agents \\((.+?)\\) reached","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/swarm/src/unified-coordinator.ts","lineNumber":305,"sourceCode":"    if (this.state.status !== 'paused') {\n      return;\n    }\n\n    this.startBackgroundProcesses();\n    this.state.status = 'running';\n\n    this.emitEvent('swarm.resumed', { swarmId: this.state.id.id });\n  }\n\n  // ===== AGENT MANAGEMENT =====\n\n  async registerAgent(\n    agentData: Omit<AgentState, 'id'>\n  ): Promise<string> {\n    const startTime = performance.now();\n\n    if (this.state.agents.size >= this.config.maxAgents) {\n      throw new Error(`Maximum agents (${this.config.maxAgents}) reached`);\n    }\n\n    this.agentCounter++;\n    const agentId: AgentId = {\n      id: `agent_${this.state.id.id}_${this.agentCounter}`,\n      swarmId: this.state.id.id,\n      type: agentData.type,\n      instance: this.agentCounter,\n    };\n\n    const agent: AgentState = {\n      ...agentData,\n      id: agentId,\n      lastHeartbeat: new Date(),\n      connections: [],\n    };\n\n    // Add to state","sourceCodeStart":287,"sourceCodeEnd":323,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/swarm/src/unified-coordinator.ts#L287-L323","documentation":"registerAgent() enforces the coordinator-level maxAgents ceiling: once state.agents.size reaches config.maxAgents, further registrations throw before an agent id is minted. This limit is independent of the TopologyManager maxAgents, so in a unified setup both limits apply and the lower one wins.","triggerScenarios":"registerAgent() calls exceeding config.maxAgents; autoscaling that registers without tracking the current count; agent entries that were never deregistered accumulating in state.agents.","commonSituations":"Raising only the topology maxAgents but not the coordinator config; long-lived swarms retaining terminated agents in state.agents; test suites sharing one coordinator instance.","solutions":["Raise maxAgents in the UnifiedSwarmCoordinator config to cover the whole fleet","Terminate or deregister idle/terminated agents before registering new ones","Pre-check with getAllAgents().length against config.maxAgents and shed load instead of throwing"],"exampleFix":"// before\nconst coordinator = new UnifiedSwarmCoordinator({ ...baseConfig, maxAgents: 8 });\nawait Promise.all(agents.map(a => coordinator.registerAgent(a))); // throws at the 9th\n\n// after\nconst coordinator = new UnifiedSwarmCoordinator({ ...baseConfig, maxAgents: agents.length + 4 });\nawait Promise.all(agents.map(a => coordinator.registerAgent(a)));","handlingStrategy":"validation","validationCode":"const current = coordinator.getAllAgents();\nif (current.length >= config.maxAgents) {\n  const idle = current.filter(a => a.status === 'idle');\n  await terminateIdleAgents(idle); // free slots before scaling up\n}\nconst agentId = await coordinator.registerAgent(agentData);","typeGuard":"function hasAgentCapacity(coordinator: UnifiedSwarmCoordinator, maxAgents: number): boolean {\n  return coordinator.getAllAgents().length < maxAgents;\n}","tryCatchPattern":"try {\n  await coordinator.registerAgent(agentData);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Maximum agents')) {\n    await terminateIdleAgents(coordinator.getAllAgents().filter(a => a.status === 'idle'));\n    return coordinator.registerAgent(agentData);\n  }\n  throw err;\n}","preventionTips":["Set coordinator maxAgents and topology maxAgents together; the lower one wins","Reap terminated agents from state.agents on shutdown paths","Autoscalers should read getAllAgents().length before deciding to spawn"],"tags":["unified-coordinator","capacity","agent-registration","max-agents"],"backgroundTag":"capacity-limit-reached","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}