ruvnet/ruflo · error

Failed to initialize @ruvector/ruvllm-wasm

Error message

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

What it means

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.

Solutions

1. Read the wrapped cause in the message — it names the failing step
2. npm install @ruvector/ruvllm-wasm (and verify node_modules/@ruvector/ruvllm-wasm/ruvllm_wasm_bg.wasm exists)
3. 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
4. Check version alignment between the loader and the wasm package; reinstall both together

Example fix

// before
await initRuvllmWasm(); // throws 'Failed to initialize @ruvector/ruvllm-wasm: ...'
// after
import { isRuvllmWasmAvailable, initRuvllmWasm } from './ruvllm-wasm';
if (!(await isRuvllmWasmAvailable())) {
  console.error('ruvllm-wasm not installed — falling back to JS tokenizer');
} else {
  try { await initRuvllmWasm(); }
  catch (e) { console.error('wasm init failed:', (e as Error).message); /* degrade gracefully */ }
}

import { isRuvllmWasmAvailable } from './ruvllm-wasm';
const canUseWasm = await isRuvllmWasmAvailable(); // probe before committing to the wasm path

import { isRuvllmWasmAvailable } from './ruvllm-wasm';
async function wasmTokenizerUsable(): Promise<boolean> {
  try { await import('@ruvector/ruvllm-wasm'); return await isRuvllmWasmAvailable(); }
  catch { return false; }
}

try {
  await initRuvllmWasm();
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failed to initialize @ruvector/ruvllm-wasm')) {
    console.warn('wasm tokenizer unavailable:', e.message); // cause is in the message
    useJsTokenizer = true; // graceful degradation
  } else throw e;
}

When it happens

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

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

Related errors

• Failed to initialize @ruvector/rvagent-wasm
• Cannot write to project path
• Contrastive loss not initialized
• Flash attention not initialized
• Hard negative miner not initialized

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

Appendix: 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 fa13ee4ad6)