Blazor AOT "Emscripten ... not found" in CI

Blazor WebAssembly AOT compiles your app to native WebAssembly with the Emscripten toolchain. When the wasm-tools workload that ships Emscripten is missing, the AOT step fails because it cannot find the toolchain.

What this error means

A publish with RunAOTCompilation=true fails during the AOT step reporting that the Emscripten SDK or its tools cannot be found.

dotnet

error : Cannot find Emscripten. The 'wasm-tools' workload may be required for AOT compilation.
error : AOT compilation failed: emcc not found on PATH.

Common causes

wasm-tools workload not installed for AOT

AOT relies on Emscripten that ships with the wasm-tools workload; without the workload, the toolchain is absent.

AOT enabled only in the CI publish profile

RunAOTCompilation is set for Release publish but local debug builds skip it, so the gap only appears in CI.

How to fix it

Install wasm-tools before the AOT publish

Run dotnet workload install wasm-tools after setup-dotnet.
Keep RunAOTCompilation on only where you intend it.
Publish in Release so the AOT step has the toolchain available.

.github/workflows/ci.yml

- run: dotnet workload install wasm-tools
- run: dotnet publish -c Release -p:RunAOTCompilation=true

Disable AOT if you do not need it

If startup AOT is not required, leave it off so the Emscripten toolchain is not needed at all.

BlazorApp.csproj

<RunAOTCompilation>false</RunAOTCompilation>

How to prevent it

Install wasm-tools whenever AOT is enabled in CI.
Keep AOT settings consistent between local and CI builds.
Cache the workload packs so AOT setup stays fast.