What causes "flashOptLevel must be between 0 and 3" in ruvnet/ruflo?

Use a value in 0, 1, 2, 3 — use 0 to disable flash optimization.

flashOptLevel must be between 0 and 3

Error message

flashOptLevel must be between 0 and 3

What it means

Thrown by AttentionCoordinator#validateConfig (v3/@claude-flow/integration/src/attention-coordinator.ts:491) when config.flashOptLevel is outside 0–3 inclusive. The level selects a Flash Attention optimization tier (0 = off, 1–3 increasing aggressiveness); anything else has no defined behavior and is rejected.

Source

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

      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
   * agentic-flow's native Flash Attention (approximate sparse attention;
   * speedup unverified — see docs/reviews/intelligence-system-audit-2026-05-29.md).
   */
  private async performAttention(params: {
    query: number[] | Float32Array;
    key: number[] | Float32Array;

View on GitHub (pinned to fa13ee4ad6)

Solutions

Use a value in 0, 1, 2, 3 — use 0 to disable flash optimization.
Clamp computed levels before constructing: Math.min(3, Math.max(0, level)).
Pin configs to the level enum documented in this package version and re-check after upgrades.

Example fix

// before
new AttentionCoordinator({ flashOptLevel: tunedLevel }); // tunedLevel = 5

// after
const flashOptLevel = Math.min(3, Math.max(0, Math.round(tunedLevel)));
new AttentionCoordinator({ flashOptLevel });

Defensive patterns

Strategy: validation

Validate before calling

const raw = Number(cfg.flashOptLevel ?? 1);
const flashOptLevel = [0, 1, 2, 3].includes(raw) ? raw : 1;
new AttentionCoordinator({ ...cfg, flashOptLevel });

Type guard

function isFlashLevel(v: unknown): v is 0 | 1 | 2 | 3 {
  return v === 0 || v === 1 || v === 2 || v === 3;
}

Try / catch

try {
  coord = new AttentionCoordinator(cfg);
} catch (e) {
  if ((e as Error).message === 'flashOptLevel must be between 0 and 3') {
    coord = new AttentionCoordinator({ ...cfg, flashOptLevel: 0 });
  } else throw e;
}

Prevention

Clamp computed optimization levels: Math.min(3, Math.max(0, level)).
Use 0 to disable flash attention — never negative values.
Re-verify the allowed range after package upgrades.

When it happens

Trigger: Passing flashOptLevel: 4 or higher after reading an outdated doc; a negative value to 'disable' instead of 0; values computed at runtime (e.g. from a heuristic) that are not clamped to the 0–3 enum.

Common situations: Version drift: an older/newer doc listing 0–5 levels; configs copied from another project with a wider scale; dynamically choosing the level from benchmark results without clamping.

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

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