dotnet "workload ... version does not match" - Update Workloads in CI

Workloads (MAUI, Android, wasm-tools, etc.) are tied to an SDK feature band. When the active SDK moves to a different band than the installed workloads target, the build complains the workload version does not match and may refuse to build.

What this error means

A workload-based build warns or fails that an installed workload’s version does not match the current SDK, or that workloads are out of date. It surfaces after an SDK bump on the runner while the workload install lagged behind.

dotnet build output

Workload version mismatch: the installed workloads target SDK band 8.0.400 but the
active SDK is 8.0.404. Run "dotnet workload update" to update installed workloads.

Common causes

SDK band changed without updating workloads

The runner’s SDK moved to a new feature band, but the previously installed workloads still target the old band, so they no longer match.

Workloads installed against a different SDK

Workloads installed for one SDK version are reported as mismatched when a different SDK is selected by PATH or global.json.

How to fix it

Restore workloads for the current project

Let the SDK install exactly the workload versions the project manifest pins.

Terminal

dotnet workload restore
dotnet build -c Release

Update workloads to the active SDK band

Bring installed workloads in line with the current SDK.