{"record":{"id":"b1695cd160f079d1","repo":"ruvnet/ruflo","slug":"pool-this-id-at-maximum-capacity-this-config","errorCode":null,"errorMessage":"Pool ${this.id} at maximum capacity (${this.config.maxWorkers} workers)","messagePattern":"Pool (.+?) at maximum capacity \\((.+?) workers\\)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/integration/src/worker-pool.ts","lineNumber":315,"sourceCode":"    this.initialized = false;\n\n    this.emit('pool-shutdown', { poolId: this.id });\n  }\n\n  /**\n   * Spawn a new worker in the pool\n   *\n   * @param config - Worker configuration\n   * @param options - Spawn options\n   * @returns Created worker\n   */\n  spawn(\n    config: WorkerConfig | SpecializedWorkerConfig | LongRunningWorkerConfig,\n    options: SpawnOptions = {}\n  ): WorkerBase {\n    // Check capacity\n    if (this.workers.size >= this.config.maxWorkers! && !options.replace) {\n      throw new Error(\n        `Pool ${this.id} at maximum capacity (${this.config.maxWorkers} workers)`\n      );\n    }\n\n    // Handle replacement\n    if (this.workers.has(config.id)) {\n      if (options.replace) {\n        this.terminate(config.id);\n      } else {\n        throw new Error(`Worker ${config.id} already exists in pool`);\n      }\n    }\n\n    // Merge with default config\n    const mergedConfig = {\n      ...this.config.defaultWorkerConfig,\n      ...config,\n    };","sourceCodeStart":297,"sourceCodeEnd":333,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/integration/src/worker-pool.ts#L297-L333","documentation":"WorkerPool.spawn enforces config.maxWorkers: once workers.size reaches the cap, further spawns throw unless options.replace is set. The pool never silently evicts workers to make room.","triggerScenarios":"Spawning a new worker when the pool already holds maxWorkers entries and SpawnOptions.replace is not true.","commonSituations":"An autoscaler spawning on demand without terminating idle workers first; a fixed pool sized too small for peak load; scale-up logic that ignores the configured cap.","solutions":["Terminate an expendable worker first (pool.terminate(id)) to free a slot, then spawn","Pass { replace: true } when the spawn is intentionally swapping an existing worker","Raise config.maxWorkers if the workload legitimately needs more"],"exampleFix":"// before\nfor (let i = 0; i < 10; i++) pool.spawn({ id: `w${i}`, type: 'coder' }); // maxWorkers=4 -> 5th call throws\n\n// after\npool.terminate(idleWorkerId()); // free a slot before hitting the cap\npool.spawn({ id: 'w5', type: 'coder' });","handlingStrategy":"validation","validationCode":"// Track pool occupancy via your own spawn/terminate accounting\nconst spawnedIds = new Set<string>();\nfunction spawnWithHeadroom(cfg: WorkerConfig, maxWorkers: number) {\n  if (spawnedIds.size >= maxWorkers) {\n    pool.terminate(pickIdleWorkerId()); // free a slot first\n    spawnedIds.delete(pickIdleWorkerId());\n  }\n  const w = pool.spawn(cfg);\n  spawnedIds.add(cfg.id);\n  return w;\n}","typeGuard":null,"tryCatchPattern":"try {\n  pool.spawn(cfg);\n} catch (e) {\n  if (e instanceof Error && /maximum capacity/.test(e.message)) {\n    // evict an idle worker and retry once, or reject the load — do not loop spawning\n  }\n  throw e;\n}","preventionTips":["Size maxWorkers from measured peak load, not average","Make autoscalers terminate-before-spawn at the cap","Expose pool occupancy in dashboards so spawns never surprise the cap"],"tags":["capacity","worker-pool","scaling","configuration"],"backgroundTag":"capacity-exceeded","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}