ruvnet/ruflo · error · Error

tuneDistillation: better-sqlite3 unavailable — cannot run…

Error message

tuneDistillation: better-sqlite3 unavailable — cannot run the tuning harness

What it means

The tuning harness depends on better-sqlite3 to open the database copies, and the dynamic loadBetterSqlite3() returned null (native module not installed or failed to load). The run aborts immediately rather than silently producing no scores; install/rebuild better-sqlite3 to use the harness.

Solutions

1. Install better-sqlite3 in the project
2. Rebuild native modules so better-sqlite3 matches the running Node ABI

Example fix

Install the better-sqlite3 dependency (npm install better-sqlite3) in the project so the tuning harness can open the source database.

When it happens

Trigger: Thrown at v3/@claude-flow/cli/src/services/distill-tuning.ts:218 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at v3/@claude-flow/cli/src/services/distill-tuning.ts:218

  const {
    dbPath,
    grid = {},
    namespaces,
    trainFraction = DEFAULT_TRAIN_FRACTION,
    queryNamespaces = DEFAULT_QUERY_NAMESPACES,
    topK = DEFAULT_TOP_K,
    now,
    tmpDir = os.tmpdir(),
    verbose = false,
  } = options;

  if (!dbPath || !fs.existsSync(dbPath)) {
    throw new Error(`tuneDistillation: source db not found at ${dbPath}`);
  }

  const Database = await loadBetterSqlite3();
  if (!Database) {
    throw new Error('tuneDistillation: better-sqlite3 unavailable — cannot run the tuning harness');
  }

  const sourceChecksumBefore = sha256File(dbPath);

  const batchSizes = grid.batchSize ?? DEFAULT_GRID_BATCH_SIZE;
  const dedupDistances = grid.dedupDistance ?? DEFAULT_GRID_DEDUP_DISTANCE;
  const promoteThresholds = grid.promoteThreshold ?? DEFAULT_GRID_PROMOTE_THRESHOLD;
  const configs: TuningConfig[] = [];
  for (const batchSize of batchSizes) {
    for (const dedupDistance of dedupDistances) {
      for (const promoteThreshold of promoteThresholds) {
        configs.push({ batchSize, dedupDistance, promoteThreshold });
      }
    }
  }
  if (configs.length === 0) {
    throw new Error('tuneDistillation: empty grid — supply at least one value per grid axis');
  }

View on GitHub (pinned to fa13ee4ad6)