Blazor "wasm-tools workload not installed" in CI

By Daniel Zoghalchali·Latchkey

Publishing a Blazor WebAssembly app with trimming or AOT needs the wasm-tools workload. A clean CI SDK does not ship it, so the build stops and tells you to run dotnet workload install wasm-tools.

What this error means

dotnet publish of a Blazor WASM project fails telling you the wasm-tools workload is required and is not installed, with the exact dotnet workload install command to run.

error : To build this project, the following workloads must be installed: wasm-tools
error : To install these workloads, run the following command: dotnet workload install wasm-tools

Common causes

The runner SDK has no optional workloads installed

GitHub-hosted images install the .NET SDK but not the optional wasm-tools workload, which Blazor WASM publish (with trimming/AOT) requires.

AOT or trimming turned on without provisioning the workload

Setting RunAOTCompilation or publish trimming pulls in the WebAssembly tools, so a build that compiled locally fails on a fresh runner.

How to fix it

Install the workload before build

1. Add a step that runs dotnet workload install wasm-tools after setup-dotnet.
2. Run it before dotnet publish or dotnet build.
3. Pin the SDK with global.json so the workload matches the band.

- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '8.0.x'
- run: dotnet workload install wasm-tools
- run: dotnet publish -c Release

Restore workloads from the manifest

If the project declares required workloads, let the SDK install exactly what the manifest lists instead of naming them by hand.

dotnet workload restore

How to prevent it

• Install wasm-tools in CI whenever the app uses trimming or AOT.
• Pin the SDK band with global.json so workload versions line up.
• Cache the workload packs between runs to cut install time.

Frequently asked questions

Related guides

References

• .NET documentation
• GitHub Actions documentation