{"record":{"id":"5265ab03f29a010f","repo":"ruvnet/ruflo","slug":"failed-to-initialize-ruvector-ruvllm-wasm-err","errorCode":null,"errorMessage":"Failed to initialize @ruvector/ruvllm-wasm: ${err}","messagePattern":"Failed to initialize @ruvector/ruvllm-wasm: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/ruvector/ruvllm-wasm.ts","lineNumber":117,"sourceCode":"  }\n}\n\n/**\n * Initialize the WASM module for Node.js. Safe to call multiple times.\n * Uses initSync with object form: { module: bytes } (raw bytes deprecated).\n */\nexport async function initRuvllmWasm(): Promise<void> {\n  if (_wasmReady) return;\n  try {\n    const mod = await import('@ruvector/ruvllm-wasm');\n    const require_ = createRequire(import.meta.url);\n    const wasmPath = require_.resolve('@ruvector/ruvllm-wasm/ruvllm_wasm_bg.wasm');\n    const wasmBytes = readFileSync(wasmPath);\n    // MUST use object form — initSync(bytes) is deprecated\n    mod.initSync({ module: wasmBytes });\n    _wasmReady = true;\n  } catch (err) {\n    throw new Error(`Failed to initialize @ruvector/ruvllm-wasm: ${err}`);\n  }\n}\n\n/**\n * Get ruvllm-wasm status.\n */\nexport async function getRuvllmStatus(): Promise<RuvllmStatus> {\n  const available = await isRuvllmWasmAvailable();\n  if (!available) {\n    return { available: false, initialized: false, version: null };\n  }\n  try {\n    const mod = await import('@ruvector/ruvllm-wasm');\n    // version is a standalone function, not on RuvLLMWasm class\n    const version = typeof mod.getVersion === 'function' ? mod.getVersion() : null;\n    return { available: true, initialized: _wasmReady, version };\n  } catch {\n    return { available: true, initialized: _wasmReady, version: null };","sourceCodeStart":99,"sourceCodeEnd":135,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/ruvector/ruvllm-wasm.ts#L99-L135","documentation":"Thrown by initRuvllmWasm() when any step of loading @ruvector/ruvllm-wasm fails: dynamic import, resolving ruvllm_wasm_bg.wasm via createRequire, readFileSync, or mod.initSync({ module: wasmBytes }). Note the object form { module: bytes } is required here (raw-bytes initSync is deprecated) — using the wrong form on an older/newer version is a common cause. The catch wraps the whole sequence so the original cause is in the interpolated ${err}.","triggerScenarios":"@ruvector/ruvllm-wasm not installed (optional dependency); the .wasm asset missing from the package; initSync signature mismatch (e.g. passing raw bytes when the module expects {module:bytes} or vice-versa across versions); Node.js < 20; broken symlink at the resolved wasm path; ESM namespace missing initSync.","commonSituations":"Bundling stripped the .wasm asset; npm install --omit=optional excluded the package; upgrading ruvllm-wasm across a major version changed the initSync contract; running on an unsupported architecture; HNSW router features that depend on this module fail to initialize.","solutions":["Confirm installation: `npm ls @ruvector/ruvllm-wasm` and verify node_modules/@ruvector/ruvllm-wasm/ruvllm_wasm_bg.wasm exists.","Reinstall without omitting optional deps; ensure Node.js >= 20.","If the error mentions initSync, check the installed version's README for the expected init form (object vs raw bytes) and adjust.","Use isRuvllmWasmAvailable() as a soft probe before init so absence is graceful rather than a thrown error."],"exampleFix":"// before\nimport { initRuvllmWasm } from './ruvllm-wasm';\nawait initRuvllmWasm();\n\n// after — probe + actionable error\nimport { initRuvllmWasm, isRuvllmWasmAvailable } from './ruvllm-wasm';\nif (!(await isRuvllmWasmAvailable())) {\n  throw new Error('ruvllm-wasm not installed — run: npm install @ruvector/ruvllm-wasm');\n}\nawait initRuvllmWasm();","handlingStrategy":"fallback","validationCode":"import { isRuvllmWasmAvailable } from './ruvllm-wasm';\n\nasync function ensureRuvllm() {\n  if (!(await isRuvllmWasmAvailable())) {\n    throw new Error(\n      '@ruvector/ruvllm-wasm not loadable. Install it: npm install @ruvector/ruvllm-wasm ' +\n      '(Node >= 20 required). If bundling, ensure the .wasm asset is copied.'\n    );\n  }\n}\n\nawait ensureRuvllm();","typeGuard":"async function canInitRuvllm(): Promise<boolean> {\n  try {\n    const mod: any = await import('@ruvector/ruvllm-wasm');\n    return typeof mod.initSync === 'function' && typeof mod.RuvLLMWasm === 'function';\n  } catch { return false; }\n}","tryCatchPattern":"try {\n  await initRuvllmWasm();\n} catch (e) {\n  // Same guidance as rvagent-wasm: do not loop — every step is deterministic.\n  if (/Cannot find module|MODULE_NOT_FOUND/.test(String(e))) {\n    console.error('Run: npm install @ruvector/ruvllm-wasm');\n  } else if (/initSync/i.test(String(e))) {\n    console.error('initSync signature changed across versions — check the installed README.');\n  }\n  throw e;\n}","preventionTips":["Pin @ruvector/ruvllm-wasm so the initSync object-form contract can't drift under you.","Always use the object form mod.initSync({ module: wasmBytes }); raw-bytes initSync is deprecated.","Run isRuvllmWasmAvailable() in health checks / `doctor` to catch absence before a real call.","When bundling, copy the .wasm asset as a static file rather than letting the bundler inline it."],"tags":["wasm","native-module","initialization","optional-dependency","ruvllm"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}