Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

dotnet: A compatible .NET SDK was not found (global.json)

The message names the file and the missing band. Relax rollForward, pin an installed version, or remove the second pin in CI.

~5 min readC#
#.NET#dotnet CLI#global.json#CI
An SDK crate stack with a mismatched version plate and an amber gap, headline SDK NOT FOUND

Introduction & Quick Summary

Symptom. Every dotnet command in a folder fails, including dotnet --version:

code
The command could not be loaded, possibly because: * You intended to execute a .NET application: The application '--version' does not exist or is not a managed .dll or .exe. * You intended to execute a .NET SDK command: A compatible .NET SDK was not found. Requested SDK version: 10.0.100 Installed SDKs: 10.0.403 [/usr/share/dotnet/sdk]

The process exits with a negative code such as -2147450725, and the CI job reports a generic failure. Nothing is wrong with the code: dotnet build fails the same way.

Cause. A global.json in the folder or in a parent folder asks for an SDK version this machine does not have, and its rollForward policy does not allow a newer one. The default policy stays inside the requested feature band, so 10.0.100 does not accept an installed 10.0.403, even though both are .NET 10.

Fix. Point the file at an installed SDK, or let it roll forward within the same major and minor.

{ "sdk": { "version": "10.0.100", "rollForward": "latestFeature" } }
bash
dotnet --list-sdks # works even when selection fails dotnet --version # now resolves

Core Mechanics, Signatures & Reproducible Setup

The dotnet host looks for global.json in the current directory and then in every parent directory, and the first file it finds wins. That is why the failure follows you into subfolders and why the message names a path you did not edit. sdk.version is a request; rollForward decides how far from it the host may move.

Reproduce it in an empty directory, which takes ten seconds and settles any argument about which value does what:

bash
mkdir /tmp/sdkprobe && cd /tmp/sdkprobe dotnet --list-sdks printf '{ "sdk": { "version": "10.0.100" } }\n' > global.json dotnet --version

Then change one field at a time and watch which versions qualify. The policy names read like English and do not behave like it, so the practical summary is worth keeping:

{ "sdk": { "version": "10.0.100", "rollForward": "latestMajor" } }

latestMajor is the loosest setting and jumps to the newest installed major, which is right for a throwaway repository and wrong for a library that publishes binaries.

Two related failures have different causes and the same symptom family:

bash
# 1. the SDK request itself: rollForward, fixed above dotnet --version # 2. an MSBuild SDK resolved from NuGet grep -rn "msbuild-sdks" NuGet.config global.json

The second gives The SDK 'Microsoft.NET.Sdk' specified could not be found, which is about SDK resolvers and package feeds, not about global.json versions.

Key Comparison Table

rollForward valueMay move toTypical use
disablenothing; exact version onlypinned build servers
latestPatchnewest patch in the same feature bandconservative default
latestFeaturenewest feature band in the same major.minormost repositories
latestMinornewest minor in the same majorapps that track minor releases
latestMajornewest installed SDKscratch projects, tools
patch (default)same feature bandinherits the strict behaviour
SymptomReal causeFix
A compatible .NET SDK was not foundglobal.json too strictrollForward or an exact installed version
dotnet --list-sdks works, --version failsselection failed after listingsame as above
NETSDK1045 targeting a newer frameworkolder SDK selectedinstall the newer SDK or retarget
SDK 'Microsoft.NET.Sdk' specified could not be foundSDK resolver or NuGet feedcheck msbuild-sdks, feeds, network
Works locally, fails in CIdifferent global.json in a parent folderprint the path from the error
MSB4236 in Visual Studio onlyVS ships one SDK copyalign the pinned band

Practical Edge Cases, Error Fixes & Deep Dive Code Examples

1. The message already names the file

Read the two lines most people skip: Requested SDK version and global.json file. If the path is above your project, someone committed it at the repository root or you cloned a repository that pins a band you do not have. dotnet --list-sdks still works because listing does not require selecting an SDK, which is what makes it the right first command.

bash
find .. -maxdepth 3 -name global.json -print cat "$(find .. -maxdepth 3 -name global.json -print -quit)"

2. CI needs one source of truth

Workflows that pass dotnet-version and repositories that pin global.json can disagree, and the failure lands on the first dotnet call:

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

Prefer the file over a version string in the workflow. When a preview band is required, keep the quality setting consistent with the pin; a workflow that installs the newest preview while global.json pins an older preview with rollForward: disable fails at every run, which is exactly how a benchmarks job can stay red for months without anyone noticing.

3. Docker images and the pinned band

The SDK image tag is itself a pin, and a global.json that asks for a different band inside the image produces the same error:

dockerfile
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build WORKDIR /src COPY global.json ./ RUN dotnet --version # fail fast with a clear line in the build log COPY . ./ RUN dotnet publish -c Release -o /app

That explicit RUN dotnet --version turns a confusing failure later in the build into a readable one at the top.

4. Visual Studio installs exactly one SDK

Upgrading Visual Studio removes the SDK the previous version installed, so a global.json that matched the old band stops matching after an IDE update. The error appears on a machine where nothing else changed, which is the confusing part. Either relax rollForward or install the required band from the download page, and remember that the build server is the place the pin actually protects.

5. latestFeature is safe, latestMajor is not

latestFeature never crosses a major version, so it cannot silently move a .NET 10 project onto .NET 11. latestMajor can, and a project that compiles against a newer SDK's analyzers and language version can produce warnings-as-errors that did not exist before. Use latestMajor for tooling repositories and never for a published library.

6. When the SDK is fine and the framework is not

NETSDK1045: The current .NET SDK does not support targeting .NET 11.0 is the other direction: the selected SDK is too old for the TargetFramework in the project file. That one is fixed by installing a newer SDK or lowering the target, not by rollForward:

xml
<PropertyGroup> <TargetFramework>net11.0</TargetFramework> </PropertyGroup>

Check what the project actually targets before editing global.json, because the two errors look similar in a CI log and have opposite fixes. Convert the resolved values into a readable form with the JSON formatter when comparing a local and a CI global.json.

Common Compilation/Runtime Mistakes & Version Gotchas

  • Deleting global.json as a quick fix. It hides the version the project is tested against, and a later SDK change reintroduces the problem with no record.
  • Matching the version string to an installed patch. That pins the project to one machine; latestFeature is the durable form.
  • Setting dotnet-version in CI and ignoring global.json. Two pins, one of which lies.
  • Assuming dotnet --version reflects the project. It reports the selected SDK for the current directory and its parents.
  • Confusing NETSDK1045 with SDK resolution. One is about the target framework, the other about the requested SDK.
  • Copying a global.json between repositories. The rollForward that suits a library breaks a tool repository and vice versa.
  • Reading the first two lines of the error. They are guesses from the host; the cause is in the requested version and the file path below them.

Reference: Select which .NET version to use and global.json overview.

Official references

primary documentation

The C# documentation that defines the behaviour this guide explains.

Try matching browser tools

All tools

Small utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.

All C# guides

More in C#

All C# guides

The guides filed next to this one in C#, in library order.