ruvnet/ruflo · error

Failed to initialize @ruvector/rvagent-wasm

Error message

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

What it means

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.

Solutions

1. Read the suffix of the message — it carries the underlying error (MODULE_NOT_FOUND vs an initSync exception) and dictates the fix
2. Reinstall cleanly: remove node_modules and lockfile artifacts, then `npm install` (or reinstall the ruflo CLI if consumed globally)
3. Upgrade Node to a current LTS — old runtimes fail initSync on newer wasm builds
4. When bundling, mark @ruvector/rvagent-wasm as external so runtime resolution works

Example fix

// before
await initAgentWasm(); // Failed to initialize @ruvector/rvagent-wasm: Cannot find module ...
// after — clean reinstall restores the wasm asset, then preflight
await initAgentWasm();
// or gate on availability first:
if (await isAgentWasmAvailable()) { /* wasm agent features */ }

// Prefer the exported availability probe before using wasm agent features
import { isAgentWasmAvailable } from '@claude-flow/cli/.../ruvector/agent-wasm.js';
if (!(await isAgentWasmAvailable())) {
  console.error('wasm agent runtime unavailable — using non-wasm paths');
}

const isWasmInitFailure = (e: unknown): e is Error =>
  e instanceof Error && /^Failed to initialize @ruvector\/rvagent-wasm/.test(e.message);

try {
  await initAgentWasm();
} catch (e) {
  if (isWasmInitFailure(e)) {
    console.error('wasm agent runtime unavailable:', e.message);
    return false; // degrade gracefully — non-wasm features still work
  }
  throw e;
}

When it happens

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

Common situations: Partial or corrupted npm installs; bundlers breaking createRequire resolution; Node versions lacking needed wasm features; pnpm strict layouts hiding the wasm file.

Related errors

• Failed to initialize @ruvector/ruvllm-wasm
• Contrastive loss not initialized
• Flash attention not initialized
• Hard negative miner not initialized
• Hyperbolic attention not initialized

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

Appendix: source

Thrown at v3/@claude-flow/cli/src/ruvector/agent-wasm.ts:91

  }
}

/**
 * Initialize the WASM module for Node.js. Safe to call multiple times.
 * Uses initSync with file-loaded WASM bytes (browser fetch doesn't work in Node).
 */
export async function initAgentWasm(): Promise<void> {
  if (_wasmReady) return;
  try {
    const mod = await import('@ruvector/rvagent-wasm');
    // In Node.js, load WASM bytes from disk and use initSync
    const require_ = createRequire(import.meta.url);
    const wasmPath = require_.resolve('@ruvector/rvagent-wasm/rvagent_wasm_bg.wasm');
    const wasmBytes = readFileSync(wasmPath);
    mod.initSync(wasmBytes);
    _wasmReady = true;
  } catch (err) {
    throw new Error(`Failed to initialize @ruvector/rvagent-wasm: ${err}`);
  }
}

// ── Agent Registry ───────────────────────────────────────────

const agents = new Map<string, { agent: any; info: WasmAgentInfo }>();
let nextId = 1;

function generateId(): string {
  return `wasm-agent-${nextId++}-${Date.now().toString(36)}`;
}

// ── Agent Lifecycle ──────────────────────────────────────────

/**
 * Create a new sandboxed WASM agent.
 */
export async function createWasmAgent(config: WasmAgentConfig = {}): Promise<WasmAgentInfo> {

View on GitHub (pinned to fa13ee4ad6)