dotnet/runtime · error · Error

This browser doesn't support WebSocket API. Please use a mod

Error message

This browser doesn't support WebSocket API. Please use a modern browser. See also https://learn.microsoft.com/aspnet/core/blazor/supported-platforms

What it means

Thrown by verifyEnvironment in the browser branch when globalThis.WebSocket is not a function, i.e. the browser is too old or an embedded WebView lacks the WebSocket API. The message links to the official Blazor supported-platforms doc.

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

  1. Use a supported modern browser (current Edge, Chrome, Firefox, Safari).
  2. Add a client-side capability check that shows an upgrade message instead of crashing.
  3. For embedded scenarios, update the host WebView/ runtime to one that implements WebSocket.

Example fix

// before: booting the runtime unconditionally
await dotnet.create();
// after: gate on WebSocket support with a user-facing message
if (typeof globalThis.WebSocket !== 'function') {
  showUpgradeNotice();
} else {
  await dotnet.create();
}
Defensive patterns

Strategy: type-guard

Validate before calling

// Gate runtime boot on browser WebSocket support
if (typeof globalThis.WebSocket !== 'function') {
  showBrowserUpgradeNotice();
} else {
  await dotnet.create();
}

Type guard

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

Prevention

When it happens

Trigger: Loading the .NET WASM runtime in a browser/WebView whose global scope has no WebSocket constructor (e.g. Internet Explorer 11, very old Safari/Android WebView).

Common situations: End users on IE11 or obsolete mobile browsers; an embedded WebView (older Android System WebView, legacy desktop shell) without modern APIs.

Related errors

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