{"record":{"id":"b21a1aa6c9893e78","repo":"ruvnet/ruflo","slug":"tunedistillation-better-sqlite3-unavailable-can","errorCode":null,"errorMessage":"tuneDistillation: better-sqlite3 unavailable — cannot run the tuning harness","messagePattern":"tuneDistillation: better-sqlite3 unavailable — cannot run the tuning harness","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/services/distill-tuning.ts","lineNumber":218,"sourceCode":"  const {\n    dbPath,\n    grid = {},\n    namespaces,\n    trainFraction = DEFAULT_TRAIN_FRACTION,\n    queryNamespaces = DEFAULT_QUERY_NAMESPACES,\n    topK = DEFAULT_TOP_K,\n    now,\n    tmpDir = os.tmpdir(),\n    verbose = false,\n  } = options;\n\n  if (!dbPath || !fs.existsSync(dbPath)) {\n    throw new Error(`tuneDistillation: source db not found at ${dbPath}`);\n  }\n\n  const Database = await loadBetterSqlite3();\n  if (!Database) {\n    throw new Error('tuneDistillation: better-sqlite3 unavailable — cannot run the tuning harness');\n  }\n\n  const sourceChecksumBefore = sha256File(dbPath);\n\n  const batchSizes = grid.batchSize ?? DEFAULT_GRID_BATCH_SIZE;\n  const dedupDistances = grid.dedupDistance ?? DEFAULT_GRID_DEDUP_DISTANCE;\n  const promoteThresholds = grid.promoteThreshold ?? DEFAULT_GRID_PROMOTE_THRESHOLD;\n  const configs: TuningConfig[] = [];\n  for (const batchSize of batchSizes) {\n    for (const dedupDistance of dedupDistances) {\n      for (const promoteThreshold of promoteThresholds) {\n        configs.push({ batchSize, dedupDistance, promoteThreshold });\n      }\n    }\n  }\n  if (configs.length === 0) {\n    throw new Error('tuneDistillation: empty grid — supply at least one value per grid axis');\n  }","sourceCodeStart":200,"sourceCodeEnd":236,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/services/distill-tuning.ts#L200-L236","documentation":"tuneDistillation needs better-sqlite3 to open read-only copies and run the candidate harness; loadBetterSqlite3() returns null when the native module cannot be loaded. Because tuning requires real sqlite I/O, an absent native binding is unrecoverable for this function (unlike the sql.js WASM path used elsewhere for persistence).","triggerScenarios":"better-sqlite3 is an optionalDependency that failed to install or load: missing native build tools at npm install, an ABI/arch mismatch (e.g. under a different Node/Electron major), the package was pruned by --omit=optional, or a corrupted prebuilt binary.","commonSituations":"CI image without build-essential / python where prebuilt binaries are unavailable for the platform; upgrading Node.js major without reinstalling native deps; running inside Electron where the ABI does not match the installed Node binding; Alpine/musl where prebuilt glibc binaries fail.","solutions":["Install/rebuild the native module: npm install better-sqlite3 (or npm rebuild better-sqlite3).","Ensure build tools are present on the host (python3, make, g++) so node-gyp can compile when no prebuilt binary matches.","On Electron, rebuild for the target ABI with electron-rebuild.","If the platform cannot provide better-sqlite3, do not call tuneDistillation — gate on a capability check first."],"exampleFix":"// before\nawait tuneDistillation({ dbPath, ... }); // throws 'better-sqlite3 unavailable'\n\n// after — gate the call\nconst Database = await loadBetterSqlite3();\nif (!Database) {\n  console.warn('better-sqlite3 missing; skipping distillation tuning');\n} else {\n  await tuneDistillation({ dbPath, ... });\n}","handlingStrategy":"validation","validationCode":"const Database = await loadBetterSqlite3();\nif (!Database) {\n  console.warn('better-sqlite3 unavailable; skipping tuneDistillation');\n} else {\n  await tuneDistillation({ dbPath, ... });\n}","typeGuard":null,"tryCatchPattern":"try {\n  await tuneDistillation({ dbPath, ... });\n} catch (e) {\n  if ((e as Error).message.includes('better-sqlite3 unavailable')) {\n    // install/rebuild the native module, then retry\n  } else throw e;\n}","preventionTips":["Install better-sqlite3 with prebuilt or build-tool support (python3, make, g++).","Rebuild native deps after a Node/Electron major upgrade (npm rebuild better-sqlite3).","Do not --omit=optional if tuning is required.","Gate tuning calls behind a loadBetterSqlite3() capability check."],"tags":["distillation","native-module","sqlite","typescript"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}