dotnet/runtime · error · Error

Please install `ws` npm package to enable networking support

Error message

Please install `ws` npm package to enable networking support.

What it means

Thrown by verifyEnvironment in the Node branch when globalThis.WebSocket is not a function. Node versions below 22 ship no built-in WebSocket, so the runtime needs the ws npm package to back System.Net.WebSockets. The message tells you exactly which dependency to install.

Source

Thrown at src/mono/browser/runtime/web-socket.ts:43

const wasm_ws_pending_close_promises = Symbol.for("wasm ws_pending_close_promises");
const wasm_ws_pending_send_promises = Symbol.for("wasm ws_pending_send_promises");
const wasm_ws_is_aborted = Symbol.for("wasm ws_is_aborted");
const wasm_ws_close_sent = Symbol.for("wasm wasm_ws_close_sent");
const wasm_ws_close_received = Symbol.for("wasm wasm_ws_close_received");
const wasm_ws_receive_status_ptr = Symbol.for("wasm ws_receive_status_ptr");

const ws_send_buffer_blocking_threshold = 65536;
const emptyBuffer = new Uint8Array();

function verifyEnvironment () {
    if (ENVIRONMENT_IS_SHELL) {
        throw new Error("WebSockets are not supported in shell JS engine.");
    }
    if (typeof globalThis.WebSocket !== "function") {
        const message = ENVIRONMENT_IS_NODE
            ? "Please install `ws` npm package to enable networking support."
            : "This browser doesn't support WebSocket API. Please use a modern browser. See also https://learn.microsoft.com/aspnet/core/blazor/supported-platforms";
        throw new Error(message);
    }
}

export function ws_get_state (ws: WebSocketExtension): number {
    if (ws.readyState != WebSocket.CLOSED)
        return ws.readyState ?? -1;
    const receive_event_queue = ws[wasm_ws_pending_receive_event_queue];
    const queued_events_count = receive_event_queue.getLength();
    if (queued_events_count == 0)
        return ws.readyState ?? -1;
    return ws[wasm_ws_close_sent] ? WebSocket.CLOSING : WebSocket.OPEN;
}

export function ws_wasm_create (uri: string, sub_protocols: string[] | null, receive_status_ptr: VoidPtr): WebSocketExtension {
    verifyEnvironment();
    assert_js_interop();
    mono_assert(uri && typeof uri === "string", () => `ERR12: Invalid uri ${typeof uri}`);
    let ws: WebSocketExtension;

View on GitHub (pinned to 290d5ab72c)

Solutions

Install the ws package in the host project: npm install ws.
Upgrade the host to Node 22+, which provides a native global WebSocket.
If ws must be loaded explicitly, assign it to globalThis.WebSocket before runtime init: globalThis.WebSocket = require('ws').WebSocket.

Example fix

// before: Node 20 host, no WebSocket polyfill
import { dotnet } from './dotnet.js';
await dotnet.create();
// after: polyfill ws before bootstrapping the runtime
globalThis.WebSocket = (await import('ws')).WebSocket;
import { dotnet } from './dotnet.js';
await dotnet.create();

Defensive patterns

Strategy: validation

Validate before calling

// Polyfill WebSocket for Node < 22 before bootstrapping the runtime
if (typeof globalThis.process !== 'undefined' && typeof globalThis.WebSocket !== 'function') {
  try {
    globalThis.WebSocket = (await import('ws')).WebSocket;
  } catch {
    throw new Error('Missing dependency: run `npm install ws` to enable WebSocket support in Node.');
  }
}

Type guard

function hasNodeWebSocket(): boolean {
  return typeof globalThis.process !== 'undefined'
    && typeof globalThis.WebSocket === 'function';
}

Prevention

Add ws to dependencies of any Node host for the runtime.
Prefer Node 22+ which provides a native global WebSocket.
Polyfill globalThis.WebSocket before calling dotnet.create().

When it happens

Trigger: Running the .NET WASM runtime under Node (<22) and calling ws_wasm_create without the ws package available, so typeof globalThis.WebSocket !== 'function'.

Common situations: Node-based SSR or test harness for Blazor/WASM; CI running on Node 18/20; ws not listed as a dependency; bundler tree-shaking ws out of the global.

Related errors

AI-assisted analysis of dotnet/runtime@290d5ab72c (2026-08-06). Data as JSON: /api/errors/320d0fe463475a86. Report an issue: GitHub.