{"record":{"id":"2239b54b4f5291c3","repo":"ruvnet/ruflo","slug":"numheads-must-be-positive","errorCode":null,"errorMessage":"numHeads must be positive","messagePattern":"numHeads must be positive","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/integration/src/attention-coordinator.ts","lineNumber":482,"sourceCode":"      flashOptLevel: config.flashOptLevel ?? 2,\n      memoryOptimization: config.memoryOptimization || 'moderate',\n    };\n  }\n\n  private initializeMetrics(): AttentionMetrics {\n    return {\n      avgLatencyMs: 0,\n      throughputTps: 0,\n      memoryEfficiency: 1.0,\n      cacheHitRate: 0,\n      totalOperations: 0,\n      speedupFactor: 1.0,\n    };\n  }\n\n  private validateConfig(): void {\n    if (this.config.numHeads <= 0) {\n      throw new Error('numHeads must be positive');\n    }\n    if (this.config.headDim <= 0) {\n      throw new Error('headDim must be positive');\n    }\n    if (this.config.dropoutRate < 0 || this.config.dropoutRate > 1) {\n      throw new Error('dropoutRate must be between 0 and 1');\n    }\n    if (this.config.flashOptLevel < 0 || this.config.flashOptLevel > 3) {\n      throw new Error('flashOptLevel must be between 0 and 3');\n    }\n  }\n\n  private async prewarmCache(): Promise<void> {\n    // Pre-compute common attention patterns\n    // This is a no-op in the simplified implementation\n  }\n\n  /**","sourceCodeStart":464,"sourceCodeEnd":500,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/integration/src/attention-coordinator.ts#L464-L500","documentation":"Thrown by AttentionCoordinator#validateConfig (v3/@claude-flow/integration/src/attention-coordinator.ts:482) when config.numHeads <= 0. numHeads is the number of attention heads; zero or negative values make attention mathematically meaningless, so construction/initialization refuses them.","triggerScenarios":"new AttentionCoordinator({ numHeads: 0 }) or a negative value; numHeads read from an env var or JSON that defaulted to 0/undefined-coerced-NaN patterns (NaN <= 0 is false, but 0 is caught); partial config objects where numHeads was expected to be defaulted but 0 was explicitly passed.","commonSituations":"Config generated from user input or a template with 0 placeholders; env var parsed with Number('') → 0; copying a config between environments where the heads field was dropped then defaulted incorrectly.","solutions":["Set a positive numHeads (typical values are powers of two, e.g. 4, 8, 16) or omit it to accept the coordinator's default.","Sanitize numeric config before constructing: coerce with Number(), then fall back to a default when !Number.isFinite(n) || n <= 0.","Fix the source of the bad value — usually an unparsed env var (NUM_HEADS='' → 0) or a placeholder config."],"exampleFix":"// before\nconst c = new AttentionCoordinator({ numHeads: Number(process.env.NUM_HEADS) }); // '' -> 0\n\n// after\nconst raw = Number(process.env.NUM_HEADS);\nconst c = new AttentionCoordinator({\n  numHeads: Number.isFinite(raw) && raw > 0 ? raw : 8,\n});","handlingStrategy":"validation","validationCode":"const n = Number(cfg.numHeads ?? 8);\nif (!Number.isFinite(n) || n <= 0) throw new Error('numHeads must be a positive finite number');\nnew AttentionCoordinator({ ...cfg, numHeads: n });","typeGuard":"function isPositiveInt(n: unknown): n is number {\n  return typeof n === 'number' && Number.isFinite(n) && n > 0;\n}","tryCatchPattern":"try {\n  coord = new AttentionCoordinator(cfg);\n} catch (e) {\n  if ((e as Error).message === 'numHeads must be positive') {\n    cfg = { ...cfg, numHeads: 8 }; // default and retry\n    coord = new AttentionCoordinator(cfg);\n  } else throw e;\n}","preventionTips":["Sanitize numeric env vars: reject empty strings before Number() coercion.","Centralize attention config parsing in one helper with defaults.","Prefer createAttentionCoordinator() so config errors surface at one call site."],"tags":["config-validation","attention","numeric-validation"],"backgroundTag":"invalid-config-value","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}