{"record":{"id":"320d0fe463475a86","repo":"dotnet/runtime","slug":"please-install-ws-npm-package-to-enable-networki","errorCode":null,"errorMessage":"Please install `ws` npm package to enable networking support.","messagePattern":"Please install `ws` npm package to enable networking support\\.","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 Node branch when globalThis.WebSocket is not a function. Node versions below 22 ship no built-in WebSocket, so the runtime needs the ws npm package to back System.Net.WebSockets. The message tells you exactly which dependency to install.","triggerScenarios":"Running the .NET WASM runtime under Node (<22) and calling ws_wasm_create without the ws package available, so typeof globalThis.WebSocket !== 'function'.","commonSituations":"Node-based SSR or test harness for Blazor/WASM; CI running on Node 18/20; ws not listed as a dependency; bundler tree-shaking ws out of the global.","solutions":["Install the ws package in the host project: npm install ws.","Upgrade the host to Node 22+, which provides a native global WebSocket.","If ws must be loaded explicitly, assign it to globalThis.WebSocket before runtime init: globalThis.WebSocket = require('ws').WebSocket."],"exampleFix":"// before: Node 20 host, no WebSocket polyfill\nimport { dotnet } from './dotnet.js';\nawait dotnet.create();\n// after: polyfill ws before bootstrapping the runtime\nglobalThis.WebSocket = (await import('ws')).WebSocket;\nimport { dotnet } from './dotnet.js';\nawait dotnet.create();","handlingStrategy":"validation","validationCode":"// Polyfill WebSocket for Node < 22 before bootstrapping the runtime\nif (typeof globalThis.process !== 'undefined' && typeof globalThis.WebSocket !== 'function') {\n  try {\n    globalThis.WebSocket = (await import('ws')).WebSocket;\n  } catch {\n    throw new Error('Missing dependency: run `npm install ws` to enable WebSocket support in Node.');\n  }\n}","typeGuard":"function hasNodeWebSocket(): boolean {\n  return typeof globalThis.process !== 'undefined'\n    && typeof globalThis.WebSocket === 'function';\n}","tryCatchPattern":null,"preventionTips":["Add ws to dependencies of any Node host for the runtime.","Prefer Node 22+ which provides a native global WebSocket.","Polyfill globalThis.WebSocket before calling dotnet.create()."],"tags":["websocket","nodejs","dependencies","networking"],"analyzedSha":"290d5ab72cc1102813fbc0406fb186ceadabc340","analyzedAt":"2026-08-06T19:57:01.276Z","schemaVersion":2},"datasetVersion":"2026-08-06T23:17:07.152Z"}