.NET "A compatible .NET SDK was not found" (global.json) in CI

By Daniel Zoghalchali·Latchkey

The runner has a .NET SDK, but global.json pins a specific version that is not installed and the roll-forward policy will not bridge the gap. The CLI refuses to run until a matching SDK is present.

What this error means

Any dotnet command fails immediately with "A compatible .NET SDK was not found." and "Requested SDK version: 8.0.401" with "global.json file: .../global.json" listing what is installed.

A compatible .NET SDK was not found.

Requested SDK version: 8.0.401
global.json file: /home/runner/work/app/global.json

Installed SDKs:
8.0.303 [/usr/share/dotnet/sdk]

Common causes

global.json pins a version not installed in CI

The exact SDK version (or feature band) in global.json is absent from the runner and the rollForward policy does not allow the installed one.

setup-dotnet provisioned a different feature band

The action installed a near version, but a strict rollForward (for example disable) requires the exact pinned build.

How to fix it

Install the exact pinned SDK

1. Read the requested version from the error.
2. Set setup-dotnet to install that SDK version.
3. Re-run; the CLI now finds a compatible SDK.

- uses: actions/setup-dotnet@v4
  with:
    global-json-file: global.json

Loosen the roll-forward policy

Allow a newer feature band so a close installed SDK satisfies the pin.

{
  "sdk": { "version": "8.0.401", "rollForward": "latestFeature" }
}

How to prevent it

• Use global-json-file with setup-dotnet so CI installs the pinned SDK.
• Choose a sensible rollForward (for example latestFeature).
• Keep global.json SDK versions current with your toolchain.

Frequently asked questions

Related guides

References

• .NET documentation
• GitHub Actions documentation