dotnet/runtime · error · Error

WebSockets are not supported in shell JS engine.

Error message

WebSockets are not supported in shell JS engine.

What it means

Thrown by verifyEnvironment when ENVIRONMENT_IS_SHELL is true, i.e. the runtime is executing under a non-browser, non-Node JS shell such as V8 d8, SpiderMonkey js, or JavaScriptCore. These shells have no networking stack, so any System.Net.WebSockets call (which routes through ws_wasm_create) is unsupported.

Source

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

const wasm_ws_pending_send_buffer_type = Symbol.for("wasm ws_pending_send_buffer_type");
const wasm_ws_pending_receive_event_queue = Symbol.for("wasm ws_pending_receive_event_queue");
const wasm_ws_pending_receive_promise_queue = Symbol.for("wasm ws_pending_receive_promise_queue");
const wasm_ws_pending_open_promise = Symbol.for("wasm ws_pending_open_promise");
const wasm_ws_pending_open_promise_used = Symbol.for("wasm wasm_ws_pending_open_promise_used");
const wasm_ws_pending_error = Symbol.for("wasm wasm_ws_pending_error");
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;
}

View on GitHub (pinned to 290d5ab72c)

Solutions

  1. Run the application in a real browser or Node.js instead of a JS shell.
  2. Guard WebSocket usage behind an environment check and skip it (or stub it) in shell contexts.
  3. For shell-based tests, mock the WebSocket interop layer or run the suite under Node with the ws package.

Example fix

// before: unconditionally opening a WebSocket from .NET in a d8 test
using var ws = new ClientWebSocket();
await ws.ConnectAsync(uri, ct);
// after: skip when running under a JS shell
if (RuntimeInformation.IsOSPlatform("BROWSER") && !IsInJsShell) { /* open ws */ }
Defensive patterns

Strategy: type-guard

Validate before calling

// Skip WebSocket workloads under a JS shell
const isShell = typeof globalThis.navigator === 'undefined'
  && typeof globalThis.WebSocket === 'undefined'
  && typeof globalThis.process === 'undefined';
if (isShell) {
  console.warn('Skipping WebSocket test; unsupported in JS shell.');
} else {
  await openWebSocket();
}

Type guard

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

Prevention

When it happens

Trigger: Running the .NET WASM runtime under d8/js/jsc and invoking ClientWebSocket or any code path that calls ws_wasm_create.

Common situations: Executing wasm unit tests under raw d8; debugging the runtime via a JS shell; running browser-targeted code in a shell harness.

Related errors

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