{"record":{"id":"feb04af4f967d492","repo":"dotnet/runtime","slug":"please-install-ws-npm-package-to-enable-networki-feb04a","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/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 Node.js (ENVIRONMENT_IS_NODE) but globalThis.WebSocket is not a function - i.e. the `ws` npm package (or a Node version >= 21 with a built-in WebSocket) is not installed/required. The dotnet wasm runtime does not bundle a WebSocket implementation for Node; it relies on the host providing one.","triggerScenarios":"Booting the dotnet wasm runtime under Node.js and calling a C# ClientWebSocket API without first making `ws` available as globalThis.WebSocket. Reached at web-socket.ts:501 via verifyEnvironment() in wsCreate().","commonSituations":"Forgetting to install the `ws` (and optionally `bufferutil`/`utf-8-validate`) dev dependency. Running in an older Node version (<21) that lacks a native WebSocket. Using a bundler that tree-shook the `ws` require. CI image that did not `npm install`.","solutions":["Install the ws package: `npm install ws` (and types: `npm install -D @types/ws`).","Before booting the runtime, assign it globally: `globalThis.WebSocket = require('ws');`.","Upgrade to Node >= 21 which ships a native globalThis.WebSocket.","Verify with a quick check `typeof globalThis.WebSocket === 'function'` before any C# WebSocket call."],"exampleFix":"// before\nconst runtime = await dotnet.create(); // then C# ClientWebSocket fails\n\n// after\nimport WebSocket from 'ws';\nglobalThis.WebSocket = WebSocket as any;\nconst runtime = await dotnet.create(); // WebSocket API now available","handlingStrategy":"validation","validationCode":"// Make `ws` available before booting the dotnet runtime in Node.\nimport { isWebSocketAvailable } from './env';\n\nfunction ensureWebSocketForNode() {\n  if (typeof process !== 'undefined' && typeof globalThis.WebSocket !== 'function') {\n    // eslint-disable-next-line @typescript-eslint/no-var-requires\n    globalThis.WebSocket = require('ws');\n  }\n}\n\nensureWebSocketForNode();\nif (typeof process !== 'undefined' && typeof globalThis.WebSocket !== 'function') {\n  throw new Error('Install the `ws` npm package or upgrade to Node >= 21');\n}","typeGuard":"function nodeHasWebSocket(): boolean {\n  return typeof process !== 'undefined' && typeof globalThis.WebSocket === 'function';\n}","tryCatchPattern":"try {\n  await dotnet.create(); // then C# ClientWebSocket.ConnectAsync\n} catch (e) {\n  if (e instanceof Error && /install .ws. npm/i.test(e.message)) {\n    throw new Error('Run `npm install ws` then assign globalThis.WebSocket = require(\"ws\") before booting the runtime.', { cause: e });\n  }\n  throw e;\n}","preventionTips":["Add `ws` to package.json devDependencies for any Node-based runtime test.","Assign globalThis.WebSocket before dotnet.create() when on Node < 21.","Use Node >= 21 to get a native globalThis.WebSocket."],"tags":["dotnet-wasm","websocket","nodejs","npm","network"],"backgroundTag":null,"analyzedSha":"60108ba66eb7d1d12f595480091b4ad80a24b172","analyzedAt":"2026-08-10T18:54:11.478Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}