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 when running under Node (ENVIRONMENT_IS_NODE) and globalThis.WebSocket is not a function. Node's stdlib does not provide WebSocket natively in older versions, so the runtime requires the `ws` npm package to be installed and registered before any WebSocket operation.

Source

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

function resolvedPromise(): Promise<void> | null {
    // 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 290d5ab72c)

Solutions

Install the package: npm install ws (and @types/ws for TS).
Ensure ws is required/imported before the runtime's first WebSocket use so globalThis.WebSocket is set.
Upgrade to a Node version (>=22) that ships a built-in WebSocket global.

Example fix

// before: nothing imported
const ws = new WebSocket(url); // globalThis.WebSocket missing

// after
import { WebSocket } from 'ws';
globalThis.WebSocket = WebSocket as any;
const ws = new WebSocket(url);

Defensive patterns

Strategy: validation

Validate before calling

function ensureWebSocketForNode() {
    if (typeof globalThis.WebSocket !== "function" && typeof require === "function") {
        try { globalThis.WebSocket = require("ws"); }
        catch { throw new Error("Install `ws`: npm install ws"); }
    }
}

Type guard

const hasWebSocket = (): boolean => typeof globalThis.WebSocket === "function";

Prevention

Add `ws` to package.json dependencies when running under Node.
Import and assign globalThis.WebSocket before starting the runtime.
Use Node >= 22 for a built-in WebSocket global.

When it happens

Trigger: Calling ClientWebSocket.ConnectAsync (or any WS API) from a .NET WASM app executed under Node, in a project where `ws` is not installed or not loaded before the runtime initializes the global.

Common situations: Fresh clone that didn't run npm install for ws; running under an older Node that lacks a built-in WebSocket; bundlers that tree-shake ws out of the global.

Related errors

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