{"record":{"id":"7a80f36e5c657fe2","repo":"dotnet/runtime","slug":"this-browser-doesn-t-support-websocket-api-please","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/mono/browser/runtime/web-socket.ts","lineNumber":43,"sourceCode":"const wasm_ws_pending_close_promises = Symbol.for(\"wasm ws_pending_close_promises\");\nconst wasm_ws_pending_send_promises = Symbol.for(\"wasm ws_pending_send_promises\");\nconst wasm_ws_is_aborted = Symbol.for(\"wasm ws_is_aborted\");\nconst wasm_ws_close_sent = Symbol.for(\"wasm wasm_ws_close_sent\");\nconst wasm_ws_close_received = Symbol.for(\"wasm wasm_ws_close_received\");\nconst wasm_ws_receive_status_ptr = Symbol.for(\"wasm ws_receive_status_ptr\");\n\nconst ws_send_buffer_blocking_threshold = 65536;\nconst emptyBuffer = new Uint8Array();\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\nexport function ws_get_state (ws: WebSocketExtension): number {\n    if (ws.readyState != WebSocket.CLOSED)\n        return ws.readyState ?? -1;\n    const receive_event_queue = ws[wasm_ws_pending_receive_event_queue];\n    const queued_events_count = receive_event_queue.getLength();\n    if (queued_events_count == 0)\n        return ws.readyState ?? -1;\n    return ws[wasm_ws_close_sent] ? WebSocket.CLOSING : WebSocket.OPEN;\n}\n\nexport function ws_wasm_create (uri: string, sub_protocols: string[] | null, receive_status_ptr: VoidPtr): WebSocketExtension {\n    verifyEnvironment();\n    assert_js_interop();\n    mono_assert(uri && typeof uri === \"string\", () => `ERR12: Invalid uri ${typeof uri}`);\n    let ws: WebSocketExtension;","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/dotnet/runtime/blob/290d5ab72cc1102813fbc0406fb186ceadabc340/src/mono/browser/runtime/web-socket.ts#L25-L61","documentation":"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.","triggerScenarios":"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).","commonSituations":"End users on IE11 or obsolete mobile browsers; an embedded WebView (older Android System WebView, legacy desktop shell) without modern APIs.","solutions":["Use a supported modern browser (current Edge, Chrome, Firefox, Safari).","Add a client-side capability check that shows an upgrade message instead of crashing.","For embedded scenarios, update the host WebView/ runtime to one that implements WebSocket."],"exampleFix":"// before: booting the runtime unconditionally\nawait dotnet.create();\n// after: gate on WebSocket support with a user-facing message\nif (typeof globalThis.WebSocket !== 'function') {\n  showUpgradeNotice();\n} else {\n  await dotnet.create();\n}","handlingStrategy":"type-guard","validationCode":"// Gate runtime boot on browser WebSocket support\nif (typeof globalThis.WebSocket !== 'function') {\n  showBrowserUpgradeNotice();\n} else {\n  await dotnet.create();\n}","typeGuard":"function browserSupportsWebSocket(): boolean {\n  return typeof globalThis !== 'undefined' && typeof globalThis.WebSocket === 'function';\n}","tryCatchPattern":null,"preventionTips":["Feature-detect WebSocket before booting the runtime and show a friendly upgrade prompt.","Document minimum browser versions to users (link the supported-platforms doc).","Keep embedded WebViews updated so they implement modern APIs."],"tags":["websocket","browser-support","environment","networking"],"analyzedSha":"290d5ab72cc1102813fbc0406fb186ceadabc340","analyzedAt":"2026-08-06T19:57:01.276Z","schemaVersion":2},"datasetVersion":"2026-08-06T23:17:07.152Z"}