Skip to main content

WebAssembly issues

System.DllNotFoundException: libSkiaSharp​

This error typically means the wasm-tools workload is not installed. Install it and rebuild:

dotnet workload install wasm-tools

If the error persists after installing the workload, add the WasmBuildNative property to your project file:

<PropertyGroup>
    <WasmBuildNative>true</WasmBuildNative>
</PropertyGroup>

Then perform a clean rebuild:

dotnet clean
dotnet build
tip

If you are using a CI/CD pipeline, make sure the wasm-tools workload is installed in your build environment before the build step runs.

Build fails with wasm-tools version mismatch​

When your .NET SDK version and the installed wasm-tools workload version are out of sync, the build can fail with cryptic errors. To fix this, update both to compatible versions:

dotnet workload update

If you pin a specific .NET SDK version in a global.json file, verify that the pinned version matches the workload you have installed.

App loads but displays a blank screen​

If your application compiles and the browser loads the page without errors, but nothing renders on screen, check the following:

  1. Browser console errors. Open your browser developer tools (F12) and look for JavaScript exceptions or failed network requests.
  2. Missing static assets. Ensure that any required static web assets (fonts, images, stylesheets) are included in the publish output. Verify the wwwroot folder contents.
  3. Incorrect entry point. Confirm that your index.html references the correct .js bootstrap file generated by the build.
  4. Content Security Policy (CSP) restrictions. If you are hosting behind a reverse proxy or CDN, confirm that your CSP headers allow wasm-eval or unsafe-eval as required by the .NET WebAssembly runtime.

Debugging WebAssembly applications​

Browser-based debugging for Avalonia WebAssembly apps requires a Chromium-based browser (Chrome or Edge). To enable debugging:

  1. Launch the app with the debugger proxy enabled:

    dotnet run --configuration Debug

  2. Open the URL shown in the console output in Chrome or Edge.

  3. Press Shift+Alt+D to open the debugging panel.

note

Breakpoint support, variable inspection, and step-through debugging are functional but may be slower than on native platforms. Hot reload is supported but may require a full page refresh for some types of changes.

CORS errors when calling external APIs​

Because your app runs inside the browser, all HTTP requests are subject to Cross-Origin Resource Sharing (CORS) policies. If your API calls fail with CORS errors:

  • Ensure the target API server returns the appropriate Access-Control-Allow-Origin headers.
  • If you control the API, add the CORS middleware or headers for your application's origin.
  • Consider using a backend proxy to forward requests when you cannot modify the target API's CORS configuration.

Large download size​

WebAssembly applications can have significant initial download sizes because the .NET runtime and all referenced assemblies are shipped to the browser. To reduce the payload:

  • Enable trimming in your project file:

    <PropertyGroup>
        <PublishTrimmed>true</PublishTrimmed>
    </PropertyGroup>

  • Enable Brotli or Gzip compression on your web server for .wasm and .dll files.

  • Remove unused NuGet package references to minimize the assembly count.

  • Use AOT compilation to improve startup performance at the cost of a larger (but faster-loading) binary:

    <PropertyGroup>
        <RunAOTCompilation>true</RunAOTCompilation>
    </PropertyGroup>
caution

Trimming can remove code that your application uses via reflection. If you see MissingMethodException or TypeLoadException errors at runtime after enabling trimming, you may need to add trim-root assemblies or DynamicDependency attributes to preserve the required types.

General limitations​

WebAssembly is a sandboxed environment with some inherent limitations:

  • Your app runs inside the browser sandbox. File system access, network access, and other OS-level APIs are restricted to what the browser permits.
  • .NET multithreading in the browser is only available starting with .NET 8, and requires specific browser support. Not all browsers support SharedArrayBuffer, which is needed for threading.
  • GUI performance can be lower than native platforms, particularly on older browsers or low-powered devices.
  • Clipboard access is limited to user-initiated events in most browsers.
  • Native file dialogs are not available. Use the browser's file input element or a JavaScript interop approach to handle file selection.

See also​

On this page