{"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":null,"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/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/cli/src/ruvector/agent-wasm.ts#L73-L109","documentation":"initAgentWasm() lazily imports @ruvector/rvagent-wasm, resolves its rvagent_wasm_bg.wasm through createRequire, and calls initSync. Any failure anywhere in that chain — missing package, unresolvable wasm subpath, initSync runtime error — is rethrown wrapped in this message with the original error stringified into it. Read past the prefix to find the real cause.","triggerScenarios":"The package absent from node_modules (optional/bundled dependency not installed); require.resolve failing on the rvagent_wasm_bg.wasm subpath (package exports map changed, version drift); initSync throwing on unsupported WebAssembly features or an old Node runtime.","commonSituations":"Partial or corrupted npm installs; bundlers breaking createRequire resolution; Node versions lacking needed wasm features; pnpm strict layouts hiding the wasm file.","solutions":["Read the suffix of the message — it carries the underlying error (MODULE_NOT_FOUND vs an initSync exception) and dictates the fix","Reinstall cleanly: remove node_modules and lockfile artifacts, then `npm install` (or reinstall the ruflo CLI if consumed globally)","Upgrade Node to a current LTS — old runtimes fail initSync on newer wasm builds","When bundling, mark @ruvector/rvagent-wasm as external so runtime resolution works"],"exampleFix":"// before\nawait initAgentWasm(); // Failed to initialize @ruvector/rvagent-wasm: Cannot find module ...\n// after — clean reinstall restores the wasm asset, then preflight\nawait initAgentWasm();\n// or gate on availability first:\nif (await isAgentWasmAvailable()) { /* wasm agent features */ }","handlingStrategy":"try-catch","validationCode":"// Prefer the exported availability probe before using wasm agent features\nimport { isAgentWasmAvailable } from '@claude-flow/cli/.../ruvector/agent-wasm.js';\nif (!(await isAgentWasmAvailable())) {\n  console.error('wasm agent runtime unavailable — using non-wasm paths');\n}","typeGuard":"const isWasmInitFailure = (e: unknown): e is Error =>\n  e instanceof Error && /^Failed to initialize @ruvector\\/rvagent-wasm/.test(e.message);","tryCatchPattern":"try {\n  await initAgentWasm();\n} catch (e) {\n  if (isWasmInitFailure(e)) {\n    console.error('wasm agent runtime unavailable:', e.message);\n    return false; // degrade gracefully — non-wasm features still work\n  }\n  throw e;\n}","preventionTips":["Clean-reinstall dependencies when CI images change Node versions","Keep Node on a current LTS for WebAssembly feature support","Mark wasm packages external when bundling the CLI","Log the wrapped cause text — it distinguishes missing-module failures from initSync failures"],"tags":["wasm","initialization","optional-dependency","node-modules"],"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"}