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 a browser-like environment (not Node, not shell) where globalThis.WebSocket is not a function. The runtime requires the standard WebSocket API; older or non-conforming browsers are rejected up front with a link to the supported-platforms doc.

Source

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

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

Upgrade to a supported modern browser (see https://learn.microsoft.com/aspnet/core/blazor/supported-platforms).
Add a WebSocket polyfill and assign it to globalThis.WebSocket before app startup.
If WebSockets are unavailable, configure a fallback transport (long polling / signalr server-sent events) on the server side.

Example fix

// before: app starts in an old browser
await app.start(); // throws verifyEnvironment

// after: polyfill before start
globalThis.WebSocket = require('websocket-polyfill').WebSocket;
await app.start();

Defensive patterns

Strategy: validation

Validate before calling

function ensureWebSocket() {
    if (typeof globalThis.WebSocket !== "function") {
        try { globalThis.WebSocket = require("websocket-polyfill").WebSocket; }
        catch { throw new Error("WebSocket unsupported; upgrade browser or add polyfill"); }
    }
}

Type guard

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

Prevention

Feature-detect WebSocket before app startup and show an upgrade message if absent.
Load a polyfill for legacy browsers, or use a server-side fallback transport.
Track the Blazor supported-platforms matrix for minimum browser versions.

When it happens

Trigger: Loading a Blazor/.NET WASM app in an old browser (legacy IE, very old Safari/Android WebView, or a locked-down embedded webview) that lacks the WebSocket constructor.

Common situations: Corporate legacy-browser baselines; embedded device WebViews stripped of WebSocket support; testing in a headless environment that is neither detected as Node nor has WebSocket (some custom harnesses).

Related errors

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