dotnet/runtime · error · Error

Please install `ws` npm package to enable networking…

Error message

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

What it means

verifyEnvironment throws this when the host is Node.js (ENVIRONMENT_IS_NODE) but globalThis.WebSocket is not a function - i.e. the `ws` npm package (or a Node version >= 21 with a built-in WebSocket) is not installed/required. The dotnet wasm runtime does not bundle a WebSocket implementation for Node; it relies on the host providing one.

Solutions

Install the ws package: `npm install ws` (and types: `npm install -D @types/ws`).
Before booting the runtime, assign it globally: `globalThis.WebSocket = require('ws');`.
Upgrade to Node >= 21 which ships a native globalThis.WebSocket.
Verify with a quick check `typeof globalThis.WebSocket === 'function'` before any C# WebSocket call.

Example fix

// before
const runtime = await dotnet.create(); // then C# ClientWebSocket fails

// after
import WebSocket from 'ws';
globalThis.WebSocket = WebSocket as any;
const runtime = await dotnet.create(); // WebSocket API now available

Defensive patterns

Strategy: validation

Validate before calling

// Make `ws` available before booting the dotnet runtime in Node.
import { isWebSocketAvailable } from './env';

function ensureWebSocketForNode() {
  if (typeof process !== 'undefined' && typeof globalThis.WebSocket !== 'function') {
    // eslint-disable-next-line @typescript-eslint/no-var-requires
    globalThis.WebSocket = require('ws');
  }
}

ensureWebSocketForNode();
if (typeof process !== 'undefined' && typeof globalThis.WebSocket !== 'function') {
  throw new Error('Install the `ws` npm package or upgrade to Node >= 21');
}

Type guard

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

Try / catch

try {
  await dotnet.create(); // then C# ClientWebSocket.ConnectAsync
} catch (e) {
  if (e instanceof Error && /install .ws. npm/i.test(e.message)) {
    throw new Error('Run `npm install ws` then assign globalThis.WebSocket = require("ws") before booting the runtime.', { cause: e });
  }
  throw e;
}

Prevention

Add `ws` to package.json devDependencies for any Node-based runtime test.
Assign globalThis.WebSocket before dotnet.create() when on Node < 21.
Use Node >= 21 to get a native globalThis.WebSocket.

When it happens

Trigger: Booting the dotnet wasm runtime under Node.js and calling a C# ClientWebSocket API without first making `ws` available as globalThis.WebSocket. Reached at web-socket.ts:501 via verifyEnvironment() in wsCreate().

Common situations: Forgetting to install the `ws` (and optionally `bufferutil`/`utf-8-validate`) dev dependency. Running in an older Node version (<21) that lacks a native WebSocket. Using a bundler that tree-shook the `ws` require. CI image that did not `npm install`.

Related errors

AI-assisted analysis of dotnet/runtime@60108ba66e (2026-08-10). Data as JSON: /api/errors/feb04af4f967d492. Report an issue: GitHub.

Appendix: source

Thrown at src/native/libs/System.Runtime.InteropServices.JavaScript.Native/interop/web-socket.ts:501

    // signal that we are finished synchronously
    // this is optimization, which doesn't allocate and doesn't require to marshal resolve() call to C# side.
    return null;
}

function rejectedPromise(message: string): Promise<any> | null {
    const resolved = Promise.reject(new Error(message));
    return wrapAsCancelable<void>(resolved);
}

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);
    }
}

View on GitHub (pinned to 60108ba66e)