{"record":{"id":"78e41ef760f6e721","repo":"ruvnet/ruflo","slug":"maximum-agent-limit-this-config-maxconcurrentag","errorCode":null,"errorMessage":"Maximum agent limit (${this.config.maxConcurrentAgents}) reached","messagePattern":"Maximum agent limit \\((.+?)\\) reached","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/plugins/src/integrations/agentic-flow.ts","lineNumber":221,"sourceCode":"    this.swarmInitialized = false;\n    this.swarmTopology = undefined;\n    this.config.logger?.info('Swarm shutdown complete');\n  }\n\n  // =========================================================================\n  // Agent Management\n  // =========================================================================\n\n  /**\n   * Spawn a new agent.\n   */\n  async spawnAgent(options: AgentSpawnOptions): Promise<SpawnedAgent> {\n    if (!this.swarmInitialized) {\n      throw new Error('Swarm not initialized');\n    }\n\n    if (this.agents.size >= (this.config.maxConcurrentAgents ?? 15)) {\n      throw new Error(`Maximum agent limit (${this.config.maxConcurrentAgents}) reached`);\n    }\n\n    const id = options.id ?? `agent-${this.nextAgentId++}`;\n\n    if (this.agents.has(id)) {\n      throw new Error(`Agent ${id} already exists`);\n    }\n\n    const agent: SpawnedAgent = {\n      id,\n      type: options.type,\n      status: 'active',\n      capabilities: options.capabilities ?? [],\n      parentId: options.parentId,\n      spawnedAt: new Date(),\n    };\n\n    this.agents.set(id, agent);","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/plugins/src/integrations/agentic-flow.ts#L203-L239","documentation":"spawnAgent() caps concurrent agents at config.maxConcurrentAgents (default 15), counting every entry in the agents map. Importantly, terminateAgent() only flips status to 'terminated' and keeps the entry in the map, so terminated agents still consume slots — the limit is reached on total registered agents, not live ones.","triggerScenarios":"Spawning the 16th agent with the default cap; bulk-spawning a worker pool larger than maxConcurrentAgents; repeatedly spawn/terminate cycles that never free slots because terminated entries remain in the map.","commonSituations":"Workloads sized above the default 15 agents; forgetting to raise maxConcurrentAgents in the integration config; assuming termination frees capacity when it does not.","solutions":["Set config.maxConcurrentAgents to your intended pool size when constructing the integration","Reuse existing active/idle agents (orchestrateTask without agentId auto-picks one) instead of spawning per task","Size spawn counts against the cap you configured, accounting for terminated-but-present entries"],"exampleFix":"// before\nconst flow = new AgenticFlowIntegration({ logger }); // default cap 15\nfor (let i = 0; i < 30; i++) await flow.spawnAgent({ type: 'coder' }); // throws at #16\n\n// after\nconst flow = new AgenticFlowIntegration({ logger, maxConcurrentAgents: 30 });\nfor (let i = 0; i < 30; i++) await flow.spawnAgent({ type: 'coder' });","handlingStrategy":"validation","validationCode":"const MAX = 30;\nconst spawned = new Set<string>();\nasync function safeSpawn(opts: AgentSpawnOptions): Promise<SpawnedAgent> {\n  if (spawned.size >= MAX) {\n    throw new Error(`agent budget exhausted (${MAX}); terminate or raise maxConcurrentAgents`);\n  }\n  const agent = await flow.spawnAgent(opts);\n  spawned.add(agent.id);\n  return agent;\n}\n// construct with matching cap: new AgenticFlowIntegration({ maxConcurrentAgents: MAX })","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set maxConcurrentAgents to your real pool size at construction","Remember terminated agents still occupy slots in this implementation","Prefer reusing active/idle agents over spawning per task"],"tags":["swarm","agents","resource-limits","capacity"],"backgroundTag":"capacity-limit-exceeded","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}