{"record":{"id":"62be13ff17f2af29","repo":"ruvnet/ruflo","slug":"headdim-must-be-positive","errorCode":null,"errorMessage":"headDim must be positive","messagePattern":"headDim must be positive","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/integration/src/attention-coordinator.ts","lineNumber":485,"sourceCode":"  }\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  /**\n   * Perform attention computation\n   *\n   * ADR-001: For sequences longer than 512 tokens, delegates to","sourceCodeStart":467,"sourceCodeEnd":503,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/integration/src/attention-coordinator.ts#L467-L503","documentation":"Thrown by AttentionCoordinator#validateConfig (v3/@claude-flow/integration/src/attention-coordinator.ts:485) when config.headDim <= 0. headDim is the per-head embedding dimension used to size projections; zero/negative dimensions cannot allocate projection buffers, so the guard rejects them at init time.","triggerScenarios":"Passing { headDim: 0 } or a negative number; deriving headDim from a model dimension divided by numHeads and getting 0 due to integer division or a wrong source dimension; a config file where headDim was left as a 0 placeholder.","commonSituations":"Mismatched model config where embeddingDim and numHeads come from different sources and the computed headDim collapses to 0; templated configs deployed with placeholder zeros; unit tests constructing minimal configs.","solutions":["Set a positive headDim (common values 32–128) or omit the field to use the built-in default.","When deriving headDim = embeddingDim / numHeads, validate the quotient is a positive integer before passing it in.","Audit config templates for 0 placeholders and replace with real values or delete the key to use defaults."],"exampleFix":"// before\nnew AttentionCoordinator({ numHeads: 8, headDim: Math.floor(dim / heads) }); // 0 when dim < heads\n\n// after\nconst headDim = Math.max(1, Math.floor(dim / heads));\nnew AttentionCoordinator({ numHeads: 8, headDim });","handlingStrategy":"validation","validationCode":"const headDim = deriveHeadDim(embeddingDim, numHeads);\nif (!Number.isFinite(headDim) || headDim <= 0) throw new Error(`bad headDim: ${headDim}`);\nnew AttentionCoordinator({ numHeads, headDim });","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 === 'headDim must be positive') {\n    coord = new AttentionCoordinator({ ...cfg, headDim: 64 });\n  } else throw e;\n}","preventionTips":["Validate derived dimensions (embeddingDim / numHeads) before use.","Keep model dimension sources consistent — do not mix configs from different models.","Omit optional numeric fields rather than passing 0 placeholders."],"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-14T00:17:10.932Z"}