ruvnet/ruflo · error · Error

Failed to initialize @ruvector/ruvllm-wasm: ${err}

Error message

Failed to initialize @ruvector/ruvllm-wasm: ${err}

What it means

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}.

Source

Thrown at v3/@claude-flow/cli/src/ruvector/ruvllm-wasm.ts:117

  }
}

/**
 * Initialize the WASM module for Node.js. Safe to call multiple times.
 * Uses initSync with object form: { module: bytes } (raw bytes deprecated).
 */
export async function initRuvllmWasm(): Promise<void> {
  if (_wasmReady) return;
  try {
    const mod = await import('@ruvector/ruvllm-wasm');
    const require_ = createRequire(import.meta.url);
    const wasmPath = require_.resolve('@ruvector/ruvllm-wasm/ruvllm_wasm_bg.wasm');
    const wasmBytes = readFileSync(wasmPath);
    // MUST use object form — initSync(bytes) is deprecated
    mod.initSync({ module: wasmBytes });
    _wasmReady = true;
  } catch (err) {
    throw new Error(`Failed to initialize @ruvector/ruvllm-wasm: ${err}`);
  }
}

/**
 * Get ruvllm-wasm status.
 */
export async function getRuvllmStatus(): Promise<RuvllmStatus> {
  const available = await isRuvllmWasmAvailable();
  if (!available) {
    return { available: false, initialized: false, version: null };
  }
  try {
    const mod = await import('@ruvector/ruvllm-wasm');
    // version is a standalone function, not on RuvLLMWasm class
    const version = typeof mod.getVersion === 'function' ? mod.getVersion() : null;
    return { available: true, initialized: _wasmReady, version };
  } catch {
    return { available: true, initialized: _wasmReady, version: null };

View on GitHub (pinned to 6b01dc5a68)

Solutions

1. Confirm installation: `npm ls @ruvector/ruvllm-wasm` and verify node_modules/@ruvector/ruvllm-wasm/ruvllm_wasm_bg.wasm exists.
2. Reinstall without omitting optional deps; ensure Node.js >= 20.
3. If the error mentions initSync, check the installed version's README for the expected init form (object vs raw bytes) and adjust.
4. Use isRuvllmWasmAvailable() as a soft probe before init so absence is graceful rather than a thrown error.

Example fix

// before
import { initRuvllmWasm } from './ruvllm-wasm';
await initRuvllmWasm();

// after — probe + actionable error
import { initRuvllmWasm, isRuvllmWasmAvailable } from './ruvllm-wasm';
if (!(await isRuvllmWasmAvailable())) {
  throw new Error('ruvllm-wasm not installed — run: npm install @ruvector/ruvllm-wasm');
}
await initRuvllmWasm();

import { isRuvllmWasmAvailable } from './ruvllm-wasm';

async function ensureRuvllm() {
  if (!(await isRuvllmWasmAvailable())) {
    throw new Error(
      '@ruvector/ruvllm-wasm not loadable. Install it: npm install @ruvector/ruvllm-wasm ' +
      '(Node >= 20 required). If bundling, ensure the .wasm asset is copied.'
    );
  }
}

await ensureRuvllm();

async function canInitRuvllm(): Promise<boolean> {
  try {
    const mod: any = await import('@ruvector/ruvllm-wasm');
    return typeof mod.initSync === 'function' && typeof mod.RuvLLMWasm === 'function';
  } catch { return false; }
}

try {
  await initRuvllmWasm();
} catch (e) {
  // Same guidance as rvagent-wasm: do not loop — every step is deterministic.
  if (/Cannot find module|MODULE_NOT_FOUND/.test(String(e))) {
    console.error('Run: npm install @ruvector/ruvllm-wasm');
  } else if (/initSync/i.test(String(e))) {
    console.error('initSync signature changed across versions — check the installed README.');
  }
  throw e;
}

When it happens

Trigger: @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.

Common situations: 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.

Related errors

• Failed to initialize @ruvector/rvagent-wasm: ${err}
• Failed to load WASM module
• MCP initialization failed: ${initResponse.error.message}
• MCP init failed
• Template not found: ${id}

AI-assisted analysis of ruvnet/ruflo@6b01dc5a68 (2026-08-12). Data as JSON: /api/errors/5265ab03f29a010f. Report an issue: GitHub.