{"record":{"id":"f4e66a2db5429515","repo":"ruvnet/ruflo","slug":"maximum-agents-this-config-maxagents-reached","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/topology-manager.ts","lineNumber":73,"sourceCode":"    this.emit('initialized', { type: this.config.type });\n  }\n\n  getState(): TopologyState {\n    return {\n      ...this.state,\n      nodes: [...this.state.nodes],\n      edges: [...this.state.edges],\n      partitions: [...this.state.partitions],\n    };\n  }\n\n  async addNode(agentId: string, role: TopologyNode['role']): Promise<TopologyNode> {\n    if (this.nodeIndex.has(agentId)) {\n      throw new Error(`Node ${agentId} already exists in topology`);\n    }\n\n    if (this.nodeIndex.size >= this.config.maxAgents) {\n      throw new Error(`Maximum agents (${this.config.maxAgents}) reached`);\n    }\n\n    // Create node with connections based on topology type\n    const connections = this.calculateInitialConnections(agentId, role);\n\n    const node: TopologyNode = {\n      id: `node_${agentId}`,\n      agentId,\n      role: this.determineRole(role),\n      status: 'syncing',\n      connections,\n      metadata: {\n        joinedAt: new Date().toISOString(),\n        version: '1.0.0',\n      },\n    };\n\n    // Add to state","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/swarm/src/topology-manager.ts#L55-L91","documentation":"addNode() enforces the maxAgents ceiling from TopologyManagerConfig: once nodeIndex.size reaches maxAgents, further adds throw before the node is created. This is a hard capacity guard, not a queue, so the caller must free slots or raise the limit. It fires after the duplicate check and creates no partial state.","triggerScenarios":"Scaling the fleet past config.maxAgents (for example a default of 8) via addNode; autoscaler loops that keep spawning; dead or stale nodes still occupying slots because removeNode was never called.","commonSituations":"Copying a topology config from a small test swarm into a larger deployment; nodes removed from the cluster but never removed from the topology; growing the fleet without touching maxAgents.","solutions":["Raise maxAgents in the topology config passed to TopologyManager.initialize so it covers the planned fleet size","removeNode() for dead or stale agents to free slots before adding new ones","In spawn loops, check current node count against maxAgents before each add"],"exampleFix":"// before\nconst topology = new TopologyManager({ type: 'mesh', maxAgents: 8 });\nawait Promise.all(agentIds.map(id => topology.addNode(id, 'worker'))); // throws once size hits 8\n\n// after\nconst topology = new TopologyManager({ type: 'mesh', maxAgents: agentIds.length + 4 });\nawait Promise.all(agentIds.map(id => topology.addNode(id, 'worker')));","handlingStrategy":"validation","validationCode":"function hasCapacity(topology: TopologyManager, maxAgents: number): boolean {\n  return topology.getState().nodes.length < maxAgents;\n}\n\nif (!hasCapacity(topology, config.maxAgents)) {\n  await evictDeadNodes(topology); // removeNode for offline agents to free slots\n}\nawait topology.addNode(agentId, 'worker');","typeGuard":"function hasCapacity(topology: TopologyManager, maxAgents: number): boolean {\n  return topology.getState().nodes.length < maxAgents;\n}","tryCatchPattern":"try {\n  await topology.addNode(agentId, 'worker');\n} catch (err) {\n  if (err instanceof Error && err.message.includes('Maximum agents')) {\n    await topology.removeNode(oldestIdleAgentId(topology));\n    return topology.addNode(agentId, 'worker');\n  }\n  throw err;\n}","preventionTips":["Size maxAgents above fleet peak, including rejoin overlap windows","Reap nodes with offline or dead status on a schedule so slots free up","Compare desired agent count to maxAgents up front in deploy scripts"],"tags":["topology","capacity","max-agents","scaling"],"backgroundTag":"capacity-limit-reached","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}