How do I prevent dotnet:NETSDK1147 in CI?

Provision workloads explicitly in CI for workload-based repositories. Pin SDK versions and keep workloads aligned with `global.json`.

How can I manually validate dotnet:NETSDK1147?

Re-run the failing command and confirm the original code/message is gone. Confirm expected artifacts or outputs exist (packages restored, build/publish succeeds).

NETSDK1147: Missing workload for the specified target framework

Fix it fast

Most likely: The project targets a workload-based platform, but that workload is not installed for the .NET SDK currently selected by this shell or CI job.

1. Confirm this is your error

error NETSDK1147: To build this project, the following workloads must be installed: maui-windows

2. Check the cause

dotnet --version
dotnet --info
dotnet workload list
cat global.json

3. Apply the safe fix

# Restore workloads required by the project for the selected SDK.
dotnet workload restore

# Or install the workload named in the NETSDK1147 message.
dotnet workload install <workload-id>
dotnet build

4. Verify it works

dotnet workload list
dotnet build

Don't use unsafe shortcuts

Do not install workloads for one SDK while global.json or CI selects another SDK.
Do not delete workload folders manually to repair a broken install, use dotnet workload repair or reinstall cleanly.
Do not treat this as a NuGet package restore problem before checking dotnet workload list.

What Broke in the Build

The project targets a workload-based platform, but the required .NET workload isn’t installed for the current SDK.

Fix the underlying build failure

Run dotnet workload restore, or dotnet workload install <id> if you need a specific workload, confirm installation with dotnet workload list, and retry with dotnet build.

Prove the Build Path Is Clean

dotnet workload list shows the required workload, and dotnet build succeeds without NETSDK1147.

Validation

Re-run the failing command and confirm the original code/message is gone, and confirm expected artifacts or outputs exist (packages restored, build/publish succeeds).

Why the Build Fails

Usually this comes down to the required workload isn’t installed on the machine or agent, the SDK version changed but workloads weren’t restored for that SDK, or workload installation is incomplete or corrupted.

Mechanism

The SDK checks for workloads needed by the target platform, such as Android, iOS, or MAUI. If they’re missing, NETSDK1147 is emitted with a workload restore or install hint.

Keep Build Prerequisites Consistent

To prevent this, provision workloads explicitly in CI for workload-based repositories, and pin SDK versions and keep workloads aligned with global.json.

Docs and source code

NETSDK1147 message template

Workload missing message template and suggested command. - GitHub

  <data name="WorkloadNotInstalled" xml:space="preserve">
    <value>NETSDK1147: To build this project, the following workloads must be installed: {0}
To install these workloads, run the following command: dotnet workload restore</value>
    <comment>{StrBegins="NETSDK1147: "}{Locked="dotnet workload restore"}</comment>
  </data>