dotnet/runtime · error · Error

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

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

verifyEnvironment throws this when the host is neither Node nor a shell (so it is assumed to be a browser) yet globalThis.WebSocket is not a function. It points the user at the Blazor supported-platforms doc because old or non-mainstream browsers (Opera Mini, old Android WebView, IE) lack the WebSocket API.

Solutions

  1. Tell users to upgrade to a supported browser (see https://learn.microsoft.com/aspnet/core/blazor/supported-platforms).
  2. Detect lack of WebSocket support in your app shell and show a user-friendly upgrade notice instead of letting the runtime throw.
  3. If you must support the environment, polyfill globalThis.WebSocket with a compatible library before booting Blazor.

Example fix

// before
await runtime.run(); // Blazor boots, user's old browser has no WebSocket -> runtime throws

// after
if (typeof globalThis.WebSocket !== 'function') {
  showUpgradeBrowserNotice();
} else {
  await runtime.run();
}
Defensive patterns

Strategy: validation

Validate before calling

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

if (!browserSupportsWebSocket()) {
  showUpgradeBrowserNotice(); // do not boot the WebSocket-dependent code path
}

Type guard

function hasBrowserWebSocket(): boolean {
  return typeof globalThis.WebSocket === 'function';
}

Try / catch

try {
  await runtime.run();
} catch (e) {
  if (e instanceof Error && /doesn.t support WebSocket API/i.test(e.message)) {
    showUpgradeBrowserNotice(); // surface a friendly upgrade prompt
    return;
  }
  throw e;
}

Prevention

When it happens

Trigger: Loading a Blazor/dotnet-wasm app in a browser that does not implement the WebSocket API and invoking a ClientWebSocket. Reached at web-socket.ts:501 (the non-Node, non-shell branch).

Common situations: End user on an old mobile browser, embedded WebView (old Android WebView, legacy Edge/IE engine), or a privacy browser that disables WebSocket. Blazor Server apps whose fallback needs WebSocket.

Related errors

AI-assisted analysis of dotnet/runtime@60108ba66e (2026-08-10). Data as JSON: /api/errors/6200e41cfafa4480. 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)