ruvnet/ruflo · error

numHeads must be positive

Error message

numHeads must be positive

What it means

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.

Source

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

      flashOptLevel: config.flashOptLevel ?? 2,
      memoryOptimization: config.memoryOptimization || 'moderate',
    };
  }

  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
  }

  /**

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Set a positive numHeads (typical values are powers of two, e.g. 4, 8, 16) or omit it to accept the coordinator's default.
2. Sanitize numeric config before constructing: coerce with Number(), then fall back to a default when !Number.isFinite(n) || n <= 0.
3. Fix the source of the bad value — usually an unparsed env var (NUM_HEADS='' → 0) or a placeholder config.

Example fix

// before
const c = new AttentionCoordinator({ numHeads: Number(process.env.NUM_HEADS) }); // '' -> 0

// after
const raw = Number(process.env.NUM_HEADS);
const c = new AttentionCoordinator({
  numHeads: Number.isFinite(raw) && raw > 0 ? raw : 8,
});

const n = Number(cfg.numHeads ?? 8);
if (!Number.isFinite(n) || n <= 0) throw new Error('numHeads must be a positive finite number');
new AttentionCoordinator({ ...cfg, numHeads: n });

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 === 'numHeads must be positive') {
    cfg = { ...cfg, numHeads: 8 }; // default and retry
    coord = new AttentionCoordinator(cfg);
  } else throw e;
}

When it happens

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

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

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

• headDim 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/2239b54b4f5291c3. Report an issue: GitHub.