{"record":{"id":"e86f6b5f901dfc59","repo":"ruvnet/ruflo","slug":"failed-to-initialize-ruvector-rvagent-wasm-err","errorCode":null,"errorMessage":"Failed to initialize @ruvector/rvagent-wasm: ${err}","messagePattern":"Failed to initialize @ruvector/rvagent-wasm: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/ruvector/agent-wasm.ts","lineNumber":91,"sourceCode":"  }\n}\n\n/**\n * Initialize the WASM module for Node.js. Safe to call multiple times.\n * Uses initSync with file-loaded WASM bytes (browser fetch doesn't work in Node).\n */\nexport async function initAgentWasm(): Promise<void> {\n  if (_wasmReady) return;\n  try {\n    const mod = await import('@ruvector/rvagent-wasm');\n    // In Node.js, load WASM bytes from disk and use initSync\n    const require_ = createRequire(import.meta.url);\n    const wasmPath = require_.resolve('@ruvector/rvagent-wasm/rvagent_wasm_bg.wasm');\n    const wasmBytes = readFileSync(wasmPath);\n    mod.initSync(wasmBytes);\n    _wasmReady = true;\n  } catch (err) {\n    throw new Error(`Failed to initialize @ruvector/rvagent-wasm: ${err}`);\n  }\n}\n\n// ── Agent Registry ───────────────────────────────────────────\n\nconst agents = new Map<string, { agent: any; info: WasmAgentInfo }>();\nlet nextId = 1;\n\nfunction generateId(): string {\n  return `wasm-agent-${nextId++}-${Date.now().toString(36)}`;\n}\n\n// ── Agent Lifecycle ──────────────────────────────────────────\n\n/**\n * Create a new sandboxed WASM agent.\n */\nexport async function createWasmAgent(config: WasmAgentConfig = {}): Promise<WasmAgentInfo> {","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/ruvector/agent-wasm.ts#L73-L109","documentation":"Thrown by initAgentWasm() when any step of loading the @ruvector/rvagent-wasm module fails: the dynamic import, resolving the .wasm asset path via createRequire, reading the wasm bytes from disk, or calling mod.initSync(wasmBytes). The catch wraps the entire init sequence and re-throws a single Error, so the original cause is stringified into the message (the ${err} interpolation). This is a hard prerequisite — no WasmAgent can be created until init succeeds.","triggerScenarios":"@ruvector/rvagent-wasm is not in node_modules (optional peer dep was skipped); the package is installed but the rvagent_wasm_bg.wasm asset is missing (broken publish); initSync is called twice with incompatible bytes after a hot-reload; Node.js version < 20 lacks WebAssembly features the module needs; the wasm file path resolves to a symlink that's broken; ESM/CJS interop returns a namespace without initSync.","commonSituations":"Running in a slimmed-down Docker image that excluded the wasm package; `npm install --omit=optional` stripped the wasm dependency; upgrading @ruvector/rvagent-wasm across a major version changed the initSync signature; bundling with esbuild/webpack dropped the .wasm asset; running on an ARM host with an x86-only prebuilt.","solutions":["Confirm the package and its wasm asset are installed: `npm ls @ruvector/rvagent-wasm` and check that node_modules/@ruvector/rvagent-wasm/rvagent_wasm_bg.wasm exists.","Reinstall: `npm install @ruvector/rvagent-wasm` (do not use --omit=optional for this dependency).","Use Node.js >= 20 (the project's documented floor) — older Node lacks the WebAssembly features the module needs.","If the error string contains 'initSync', verify you haven't already initialized the module in a long-running process; the _wasmReady guard should prevent this, but a forked worker may re-enter.","If bundling, ensure the .wasm file is copied as a static asset rather than inlined."],"exampleFix":"// before — assumes package is always present\nimport { initAgentWasm } from './agent-wasm';\nawait initAgentWasm();\n\n// after — guard with availability check and surface a actionable error\nimport { initAgentWasm, isAgentWasmAvailable } from './agent-wasm';\nif (!(await isAgentWasmAvailable())) {\n  throw new Error('rvagent-wasm not installed — run: npm install @ruvector/rvagent-wasm');\n}\nawait initAgentWasm();","handlingStrategy":"fallback","validationCode":"import { isAgentWasmAvailable } from './agent-wasm';\n\nasync function ensureAgentWasm() {\n  if (!(await isAgentWasmAvailable())) {\n    throw new Error(\n      '@ruvector/rvagent-wasm not loadable. Install it: npm install @ruvector/rvagent-wasm ' +\n      '(Node >= 20 required). If bundling, ensure the .wasm asset is copied.'\n    );\n  }\n}\n\n// run before any code path that needs a WasmAgent\nawait ensureAgentWasm();","typeGuard":"async function canInitAgentWasm(): Promise<boolean> {\n  try {\n    const mod: any = await import('@ruvector/rvagent-wasm');\n    return typeof mod.initSync === 'function' && typeof mod.WasmAgent === 'function';\n  } catch { return false; }\n}","tryCatchPattern":"try {\n  await initAgentWasm();\n} catch (e) {\n  // Degrade to a non-WASM code path or surface an actionable install hint.\n  // Do not loop — every step (import, resolve, read, initSync) is deterministic.\n  if (/Cannot find module|MODULE_NOT_FOUND/.test(String(e))) {\n    console.error('Run: npm install @ruvector/ruvllm-wasm');\n  }\n  throw e;\n}","preventionTips":["Pin @ruvector/rvagent-wasm in package.json so the initSync contract can't drift under you.","Don't use --omit=optional in install commands that need this package.","When bundling, copy the .wasm asset as a static file rather than letting the bundler inline it.","Run isAgentWasmAvailable() during health checks / `doctor` so absence is detected before a real call."],"tags":["wasm","native-module","initialization","optional-dependency"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}