{"record":{"id":"40dabec704ec79bb","repo":"dotnet/aspnetcore","slug":"this-browser-does-not-support-webassembly","errorCode":null,"errorMessage":"This browser does not support WebAssembly.","messagePattern":"This browser does not support WebAssembly\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/Components/Web.JS/src/Platform/Mono/MonoPlatform.ts","lineNumber":124,"sourceCode":"    assertHeapIsNotLocked();\n    currentHeapLock = MonoHeapLock.create();\n    return currentHeapLock;\n  },\n\n  invokeWhenHeapUnlocked: function invokeWhenHeapUnlocked(callback) {\n    // This is somewhat like a sync context. If we're not locked, just pass through the call directly.\n    if (!currentHeapLock) {\n      callback();\n    } else {\n      currentHeapLock.enqueuePostReleaseAction(callback);\n    }\n  },\n};\n\nasync function importDotnetJs(startOptions: Partial<WebAssemblyStartOptions>): Promise<ModuleAPI> {\n  const browserSupportsNativeWebAssembly = typeof WebAssembly !== 'undefined' && WebAssembly.validate;\n  if (!browserSupportsNativeWebAssembly) {\n    throw new Error('This browser does not support WebAssembly.');\n  }\n\n\n  // Allow overriding the URI from which the dotnet.*.js file is loaded\n  if (startOptions.loadBootResource) {\n    const resourceType: WebAssemblyBootResourceType = 'dotnetjs';\n    const customSrc = startOptions.loadBootResource(resourceType, 'dotnet.js', '_framework/dotnet.js', '', 'js-module-dotnet');\n    if (typeof (customSrc) === 'string') {\n      const absoluteSrc = (new URL(customSrc, document.baseURI)).toString();\n      return await import(/* webpackIgnore: true */ absoluteSrc);\n    } else if (customSrc) {\n      // Since we must load this via a import, it's only valid to supply a URI (and not a Request, say)\n      throw new Error(`For a ${resourceType} resource, custom loaders must supply a URI string.`);\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/ban-ts-comment\n  // @ts-ignore: This dynamic import is handled at runtime and does not need a type declaration.","sourceCodeStart":106,"sourceCodeEnd":142,"githubUrl":"https://github.com/dotnet/aspnetcore/blob/3600ca084e9c8b5f4174fc5e747f4c52d2100806/src/Components/Web.JS/src/Platform/Mono/MonoPlatform.ts#L106-L142","documentation":"`importDotnetJs` is the entry point for loading the .NET WebAssembly runtime in a Blazor WebAssembly app. It first checks that the browser exposes a usable `WebAssembly` global and that `WebAssembly.validate` exists; if not, the runtime cannot be instantiated and startup aborts with this error. It is a hard environment prerequisite, not a recoverable config issue.","triggerScenarios":"Starting a Blazor WebAssembly app in a browser/engine without the `WebAssembly` global or where `WebAssembly.validate` is missing — older browsers (pre-2017), some embedded webviews, locked-down environments, or non-browser JS hosts (Node without a WASM polyfill).","commonSituations":"Targeting legacy browsers the app doesn't support; an in-app webview (older Cordova/Capacitor/UWP) with WASM disabled; bot/crawler or SSR-only fetch hitting the boot path; corporate policy stripping `WebAssembly`; testing under a headless runner that lacks WASM.","solutions":["Require a modern, WASM-capable browser and communicate that to users (Blazor WebAssembly needs a current Edge/Chrome/Firefox/Safari).","Update the host webview/WebView2 to a version that includes WebAssembly.","If you must support WASM-less clients, detect it and serve a static/SSR fallback instead of starting the WASM app.","Confirm `WebAssembly` is present in the failing environment via a console check before reporting."],"exampleFix":"// before\nBlazor.start(); // throws 'This browser does not support WebAssembly.'\n\n// after\nif (typeof WebAssembly === 'undefined' || !WebAssembly.validate) {\n  showBrowserUpgradeNotice();\n} else {\n  await Blazor.start();\n}","handlingStrategy":"fallback","validationCode":"function supportsWasm(): boolean {\n  return typeof WebAssembly !== 'undefined' && !!WebAssembly.validate;\n}","typeGuard":"function browserSupportsWasm(): boolean {\n  return typeof WebAssembly === 'object' && typeof WebAssembly.validate === 'function';\n}","tryCatchPattern":"try { await Blazor.start(); }\ncatch (e) { if (/does not support WebAssembly/.test(e.message)) { showUpgradeNotice(); return; } throw e; }","preventionTips":["Detect WebAssembly support before starting and show an upgrade notice.","Target only WASM-capable browsers in your support matrix.","Keep host webviews (WebView2) updated.","Serve a static/SSR fallback for unsupported clients."],"tags":["webassembly","blazor-wasm","runtime","browser-support","startup"],"backgroundTag":null,"analyzedSha":"3600ca084e9c8b5f4174fc5e747f4c52d2100806","analyzedAt":"2026-08-11T16:32:30.678Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}