{"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":null,"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/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/ruvector/ruvllm-wasm.ts#L99-L135","documentation":"initRuvllmWasm() dynamically imports @ruvector/ruvllm-wasm, resolves the wasm binary via require.resolve('@ruvector/ruvllm-wasm/ruvllm_wasm_bg.wasm'), reads it with readFileSync, and calls initSync({module}). Any failure at any of those steps is re-thrown wrapped as this error with the underlying cause in the message — so the real reason (module not found, wasm path unresolvable, init failure) is the text after the colon.","triggerScenarios":"The @ruvector/ruvllm-wasm package (or its optional deps) is not installed — dynamic import rejects; require.resolve cannot find the .wasm entry (exports map or missing file); running inside a bundler/browser where import.meta.url+createRequire or readFileSync is unavailable; version skew between the JS glue and the wasm binary breaking initSync.","commonSituations":"npm install --production/--omit=optional pruning the wasm package; esbuild/webpack single-file builds that strip .wasm assets and break createRequire; ESM setups without filesystem access to node_modules; partial installs or corrupted caches; switching Node major versions with an incompatible prebuilt wasm.","solutions":["Read the wrapped cause in the message — it names the failing step","npm install @ruvector/ruvllm-wasm (and verify node_modules/@ruvector/ruvllm-wasm/ruvllm_wasm_bg.wasm exists)","Run under Node.js with intact node_modules; do not single-file-bundle this module — mark it external and ship the .wasm as an asset","Check version alignment between the loader and the wasm package; reinstall both together"],"exampleFix":"// before\nawait initRuvllmWasm(); // throws 'Failed to initialize @ruvector/ruvllm-wasm: ...'\n// after\nimport { isRuvllmWasmAvailable, initRuvllmWasm } from './ruvllm-wasm';\nif (!(await isRuvllmWasmAvailable())) {\n  console.error('ruvllm-wasm not installed — falling back to JS tokenizer');\n} else {\n  try { await initRuvllmWasm(); }\n  catch (e) { console.error('wasm init failed:', (e as Error).message); /* degrade gracefully */ }\n}","handlingStrategy":"fallback","validationCode":"import { isRuvllmWasmAvailable } from './ruvllm-wasm';\nconst canUseWasm = await isRuvllmWasmAvailable(); // probe before committing to the wasm path","typeGuard":"import { isRuvllmWasmAvailable } from './ruvllm-wasm';\nasync function wasmTokenizerUsable(): Promise<boolean> {\n  try { await import('@ruvector/ruvllm-wasm'); return await isRuvllmWasmAvailable(); }\n  catch { return false; }\n}","tryCatchPattern":"try {\n  await initRuvllmWasm();\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Failed to initialize @ruvector/ruvllm-wasm')) {\n    console.warn('wasm tokenizer unavailable:', e.message); // cause is in the message\n    useJsTokenizer = true; // graceful degradation\n  } else throw e;\n}","preventionTips":["Mark @ruvector/ruvllm-wasm external in bundler configs and ship the .wasm file as an asset","Include the wasm package in lockfile-driven installs; do not prune optional deps blindly","Always feature-detect (isRuvllmWasmAvailable) and keep a non-wasm fallback path"],"tags":["wasm","initialization","optional-dependency","bundler","nodejs"],"backgroundTag":"wasm-initialization-failed","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}