{"record":{"id":"7940420b033a5557","repo":"dotnet/runtime","slug":"websockets-are-not-supported-in-shell-js-engine-794042","errorCode":null,"errorMessage":"WebSockets are not supported in shell JS engine.","messagePattern":"WebSockets are not supported in shell JS engine\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/native/libs/System.Runtime.InteropServices.JavaScript.Native/interop/web-socket.ts","lineNumber":495,"sourceCode":"    type: number, // WebSocketMessageType\n    data: Uint8Array,\n    offset: number\n}\n\nfunction resolvedPromise(): Promise<void> | null {\n    // 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":477,"sourceCodeEnd":504,"githubUrl":"https://github.com/dotnet/runtime/blob/60108ba66eb7d1d12f595480091b4ad80a24b172/src/native/libs/System.Runtime.InteropServices.JavaScript.Native/interop/web-socket.ts#L477-L504","documentation":"verifyEnvironment throws this when ENVIRONMENT_IS_SHELL is true - i.e. the dotnet wasm runtime is running inside a JS shell interpreter (V8 d8, SpiderMonkey js, JavaScriptCore jsc, etc.) rather than a browser or Node. Those shells have no networking or WebSocket implementation, so the .NET ClientWebSocket implementation cannot operate.","triggerScenarios":"Calling any ClientWebSocket API (ConnectAsync, or the runtime's wsCreate path) while the wasm runtime was booted inside d8/js/jsc. Reached at web-socket.ts:495 in verifyEnvironment(), which wsCreate calls before opening a socket.","commonSituations":"Running dotnet unit tests or smoke tests under d8/jsc and exercising a WebSocket code path. Using a JS shell as a lightweight host and forgetting it lacks networking. CI that picks the shell engine by default for speed.","solutions":["Run the same workload under a browser or Node.js host instead of a JS shell.","Skip or stub WebSocket-dependent tests when the host is a JS shell (gate on ENVIRONMENT_IS_SHELL in test setup).","If you must use a shell, provide a WebSocket polyfill globalThis.WebSocket before the runtime initializes (uncommon; prefer Node)."],"exampleFix":"// before: tests run under d8 and invoke ClientWebSocket\n\n// after: route WebSocket tests to Node runner\n//   node --experimental-wasm-bigint test-runner.js  (provides globalThis.Webrtc/globalThis.WebSocket via ws)","handlingStrategy":"validation","validationCode":"// Detect a JS shell host before booting dotnet, and skip WebSocket code paths.\nfunction isJsShellHost(): boolean {\n  // Heuristic: shells like d8/jsc lack a `window`/`self` and lack `WebSocket`.\n  return typeof globalThis.WebSocket !== 'function'\n    && typeof (globalThis as any).window === 'undefined'\n    && typeof (globalThis as any).self === 'undefined'\n    && typeof process === 'undefined';\n}\n\nif (isJsShellHost()) {\n  console.warn('Skipping WebSocket tests: JS shell has no networking.');\n}","typeGuard":"function supportsWebSocket(): boolean {\n  return typeof globalThis.WebSocket === 'function';\n}","tryCatchPattern":"try {\n  await clientWebSocket.ConnectAsync(uri, ct);\n} catch (e) {\n  if (e instanceof Error && /shell JS engine/i.test(e.message)) {\n    // Re-run under Node or a browser instead of a JS shell.\n    throw new Error('WebSocket not available in JS shell host; switch to Node/browser.', { cause: e });\n  }\n  throw e;\n}","preventionTips":["Do not run WebSocket-dependent tests under d8/jsc/js shells.","Gate WebSocket tests on `typeof globalThis.WebSocket === 'function'`.","Use Node (with the `ws` package) or a real browser for networking tests."],"tags":["dotnet-wasm","websocket","environment","js-shell","network"],"backgroundTag":null,"analyzedSha":"60108ba66eb7d1d12f595480091b4ad80a24b172","analyzedAt":"2026-08-10T18:54:11.478Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}