ruvnet/ruflo · error · Error

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

Error message

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

What it means

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.

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 6b01dc5a68)

Solutions

1. 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.
2. Reinstall: `npm install @ruvector/rvagent-wasm` (do not use --omit=optional for this dependency).
3. Use Node.js >= 20 (the project's documented floor) — older Node lacks the WebAssembly features the module needs.
4. 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.
5. If bundling, ensure the .wasm file is copied as a static asset rather than inlined.

Example fix

// before — assumes package is always present
import { initAgentWasm } from './agent-wasm';
await initAgentWasm();

// after — guard with availability check and surface a actionable error
import { initAgentWasm, isAgentWasmAvailable } from './agent-wasm';
if (!(await isAgentWasmAvailable())) {
  throw new Error('rvagent-wasm not installed — run: npm install @ruvector/rvagent-wasm');
}
await initAgentWasm();

import { isAgentWasmAvailable } from './agent-wasm';

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

// run before any code path that needs a WasmAgent
await ensureAgentWasm();

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

try {
  await initAgentWasm();
} catch (e) {
  // Degrade to a non-WASM code path or surface an actionable install hint.
  // Do not loop — every step (import, resolve, read, initSync) is deterministic.
  if (/Cannot find module|MODULE_NOT_FOUND/.test(String(e))) {
    console.error('Run: npm install @ruvector/ruvllm-wasm');
  }
  throw e;
}

When it happens

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

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

Related errors

• Failed to initialize @ruvector/ruvllm-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/e86f6b5f901dfc59. Report an issue: GitHub.