Running RivetKit locally on Windows (no WSL) via setupTest() fails in two connected ways, because Windows has no native @rivetkit/engine-cli-* binary and falls back to a WASM-only runtime, but that fallback path isn't fully supported by the local dev/test flow.
Environment
OS: Windows (native, not WSL)
Node.js: v22.23.2
npm: 10.9.8
rivetkit: 2.3.10
Issue 1: WASM loader uses fetch() on a file: URL, which Node doesn't support
@rivetkit/rivetkit-wasm's loader (pkg/rivetkit_wasm.js, generated by wasm-bindgen's --target web output) defaults to:
fetch(new URL('rivetkit_wasm_bg.wasm', import.meta.url))
On Node, this resolves to a file:// URL. Node's built-in fetch (undici) does not implement the file: scheme, only http(s). This throws immediately:
TypeError: fetch failed: not implemented... yet...
before any actor code runs.
Workaround found: pass the wasm bytes directly via the already-supported wasm.initInput config option, bypassing fetch() entirely:
const require = createRequire(import.meta.url);
const wasmPath = require.resolve("@rivetkit/rivetkit-wasm/rivetkit_wasm_bg.wasm");
const wasmBytes = readFileSync(wasmPath);
export const registry = setup({
use: { taskBoard },
wasm: { initInput: wasmBytes },
});
Issue 2: after that workaround, the WASM runtime rejects the default engine_binary_path config
With the above fix applied, setupTest() still fails, now with:
RivetError: Invalid wasm configuration field 'engine_binary_path': wasm runtimes cannot spawn an engine binary; omit this field and connect to an existing engine endpoint
followed by repeated failed metadata fetches to http://127.0.0.1:6420/ and a 30s timeout.
It looks like the default local/test config path assumes a native engine binary can be spawned, which is true on Linux/macOS where a prebuilt binary ships, but on Windows, where the runtime silently falls back to WASM-only, that same default config is invalid, and nothing auto-starts a connectible engine instead.
Suggested fix / ask
Either ship a native Windows engine binary matching the Linux/macOS packages, or have the WASM fallback path auto-omit engine_binary_path and self-manage a connectible engine endpoint the way native platforms do, or at minimum surface a clear error or docs note that Windows users currently need WSL, Docker, or a manually-run engine instance for local dev/testing, since the failure mode otherwise looks like a generic timeout with no clear cause.
Reproduction
Confirmed working around this in WSL2 instead, the exact same project runs cleanly there since it picks up the native Linux engine binary. Minimal repro project: https://github.com/Chandanac52/rivetkit_taskboard.git
Running RivetKit locally on Windows (no WSL) via setupTest() fails in two connected ways, because Windows has no native @rivetkit/engine-cli-* binary and falls back to a WASM-only runtime, but that fallback path isn't fully supported by the local dev/test flow.
Environment
OS: Windows (native, not WSL)
Node.js: v22.23.2
npm: 10.9.8
rivetkit: 2.3.10
Issue 1: WASM loader uses fetch() on a file: URL, which Node doesn't support
@rivetkit/rivetkit-wasm's loader (pkg/rivetkit_wasm.js, generated by wasm-bindgen's --target web output) defaults to:
fetch(new URL('rivetkit_wasm_bg.wasm', import.meta.url))
On Node, this resolves to a file:// URL. Node's built-in fetch (undici) does not implement the file: scheme, only http(s). This throws immediately:
TypeError: fetch failed: not implemented... yet...
before any actor code runs.
Workaround found: pass the wasm bytes directly via the already-supported wasm.initInput config option, bypassing fetch() entirely:
const require = createRequire(import.meta.url);
const wasmPath = require.resolve("@rivetkit/rivetkit-wasm/rivetkit_wasm_bg.wasm");
const wasmBytes = readFileSync(wasmPath);
export const registry = setup({
use: { taskBoard },
wasm: { initInput: wasmBytes },
});
Issue 2: after that workaround, the WASM runtime rejects the default engine_binary_path config
With the above fix applied, setupTest() still fails, now with:
RivetError: Invalid wasm configuration field 'engine_binary_path': wasm runtimes cannot spawn an engine binary; omit this field and connect to an existing engine endpoint
followed by repeated failed metadata fetches to http://127.0.0.1:6420/ and a 30s timeout.
It looks like the default local/test config path assumes a native engine binary can be spawned, which is true on Linux/macOS where a prebuilt binary ships, but on Windows, where the runtime silently falls back to WASM-only, that same default config is invalid, and nothing auto-starts a connectible engine instead.
Suggested fix / ask
Either ship a native Windows engine binary matching the Linux/macOS packages, or have the WASM fallback path auto-omit engine_binary_path and self-manage a connectible engine endpoint the way native platforms do, or at minimum surface a clear error or docs note that Windows users currently need WSL, Docker, or a manually-run engine instance for local dev/testing, since the failure mode otherwise looks like a generic timeout with no clear cause.
Reproduction
Confirmed working around this in WSL2 instead, the exact same project runs cleanly there since it picks up the native Linux engine binary. Minimal repro project: https://github.com/Chandanac52/rivetkit_taskboard.git