ruvnet/ruflo · error

headDim must be positive

Error message

headDim must be positive

What it means

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.

Source

Thrown at v3/@claude-flow/integration/src/attention-coordinator.ts:485

  }

  private initializeMetrics(): AttentionMetrics {
    return {
      avgLatencyMs: 0,
      throughputTps: 0,
      memoryEfficiency: 1.0,
      cacheHitRate: 0,
      totalOperations: 0,
      speedupFactor: 1.0,
    };
  }

  private validateConfig(): void {
    if (this.config.numHeads <= 0) {
      throw new Error('numHeads must be positive');
    }
    if (this.config.headDim <= 0) {
      throw new Error('headDim must be positive');
    }
    if (this.config.dropoutRate < 0 || this.config.dropoutRate > 1) {
      throw new Error('dropoutRate must be between 0 and 1');
    }
    if (this.config.flashOptLevel < 0 || this.config.flashOptLevel > 3) {
      throw new Error('flashOptLevel must be between 0 and 3');
    }
  }

  private async prewarmCache(): Promise<void> {
    // Pre-compute common attention patterns
    // This is a no-op in the simplified implementation
  }

  /**
   * Perform attention computation
   *
   * ADR-001: For sequences longer than 512 tokens, delegates to

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Set a positive headDim (common values 32–128) or omit the field to use the built-in default.
2. When deriving headDim = embeddingDim / numHeads, validate the quotient is a positive integer before passing it in.
3. Audit config templates for 0 placeholders and replace with real values or delete the key to use defaults.

Example fix

// before
new AttentionCoordinator({ numHeads: 8, headDim: Math.floor(dim / heads) }); // 0 when dim < heads

// after
const headDim = Math.max(1, Math.floor(dim / heads));
new AttentionCoordinator({ numHeads: 8, headDim });

const headDim = deriveHeadDim(embeddingDim, numHeads);
if (!Number.isFinite(headDim) || headDim <= 0) throw new Error(`bad headDim: ${headDim}`);
new AttentionCoordinator({ numHeads, headDim });

function isPositiveInt(n: unknown): n is number {
  return typeof n === 'number' && Number.isFinite(n) && n > 0;
}

try {
  coord = new AttentionCoordinator(cfg);
} catch (e) {
  if ((e as Error).message === 'headDim must be positive') {
    coord = new AttentionCoordinator({ ...cfg, headDim: 64 });
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• numHeads must be positive
• dropoutRate must be between 0 and 1
• flashOptLevel must be between 0 and 3
• SemanticRouter requires a dimension in config
• Flash attention not initialized

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/62be13ff17f2af29. Report an issue: GitHub.