{"record":{"id":"6200e41cfafa4480","repo":"dotnet/runtime","slug":"this-browser-doesn-t-support-websocket-api-please-6200e4","errorCode":null,"errorMessage":"This browser doesn't support WebSocket API. Please use a modern browser. See also https://learn.microsoft.com/aspnet/core/blazor/supported-platforms","messagePattern":"This browser doesn't support WebSocket API\\. Please use a modern browser\\. See also https://learn\\.microsoft\\.com/aspnet/core/blazor/supported-platforms","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/native/libs/System.Runtime.InteropServices.JavaScript.Native/interop/web-socket.ts","lineNumber":501,"sourceCode":"    // signal that we are finished synchronously\n    // this is optimization, which doesn't allocate and doesn't require to marshal resolve() call to C# side.\n    return null;\n}\n\nfunction rejectedPromise(message: string): Promise<any> | null {\n    const resolved = Promise.reject(new Error(message));\n    return wrapAsCancelable<void>(resolved);\n}\n\nfunction verifyEnvironment() {\n    if (ENVIRONMENT_IS_SHELL) {\n        throw new Error(\"WebSockets are not supported in shell JS engine.\");\n    }\n    if (typeof globalThis.WebSocket !== \"function\") {\n        const message = ENVIRONMENT_IS_NODE\n            ? \"Please install `ws` npm package to enable networking support.\"\n            : \"This browser doesn't support WebSocket API. Please use a modern browser. See also https://learn.microsoft.com/aspnet/core/blazor/supported-platforms\";\n        throw new Error(message);\n    }\n}\n","sourceCodeStart":483,"sourceCodeEnd":504,"githubUrl":"https://github.com/dotnet/runtime/blob/60108ba66eb7d1d12f595480091b4ad80a24b172/src/native/libs/System.Runtime.InteropServices.JavaScript.Native/interop/web-socket.ts#L483-L504","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Tell users to upgrade to a supported browser (see https://learn.microsoft.com/aspnet/core/blazor/supported-platforms).","Detect lack of WebSocket support in your app shell and show a user-friendly upgrade notice instead of letting the runtime throw.","If you must support the environment, polyfill globalThis.WebSocket with a compatible library before booting Blazor."],"exampleFix":"// before\nawait runtime.run(); // Blazor boots, user's old browser has no WebSocket -> runtime throws\n\n// after\nif (typeof globalThis.WebSocket !== 'function') {\n  showUpgradeBrowserNotice();\n} else {\n  await runtime.run();\n}","handlingStrategy":"validation","validationCode":"function browserSupportsWebSocket(): boolean {\n  return typeof window !== 'undefined' && typeof globalThis.WebSocket === 'function';\n}\n\nif (!browserSupportsWebSocket()) {\n  showUpgradeBrowserNotice(); // do not boot the WebSocket-dependent code path\n}","typeGuard":"function hasBrowserWebSocket(): boolean {\n  return typeof globalThis.WebSocket === 'function';\n}","tryCatchPattern":"try {\n  await runtime.run();\n} catch (e) {\n  if (e instanceof Error && /doesn.t support WebSocket API/i.test(e.message)) {\n    showUpgradeBrowserNotice(); // surface a friendly upgrade prompt\n    return;\n  }\n  throw e;\n}","preventionTips":["Detect missing WebSocket before booting Blazor and show an upgrade prompt.","Document supported browsers per the Blazor supported-platforms page.","Provide a polyfill only as a last resort; prefer asking the user to upgrade."],"tags":["dotnet-wasm","blazor","websocket","browser-support","network"],"backgroundTag":null,"analyzedSha":"60108ba66eb7d1d12f595480091b4ad80a24b172","analyzedAt":"2026-08-10T18:54:11.478Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}