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.

Introduction & Quick Summary
Symptom. Every dotnet command in a folder fails, including dotnet --version:
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"
}
}dotnet --list-sdks # works even when selection fails
dotnet --version # now resolvesCore 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:
mkdir /tmp/sdkprobe && cd /tmp/sdkprobe
dotnet --list-sdks
printf '{ "sdk": { "version": "10.0.100" } }\n' > global.json
dotnet --versionThen 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:
# 1. the SDK request itself: rollForward, fixed above
dotnet --version
# 2. an MSBuild SDK resolved from NuGet
grep -rn "msbuild-sdks" NuGet.config global.jsonThe 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 value | May move to | Typical use |
|---|---|---|
disable | nothing; exact version only | pinned build servers |
latestPatch | newest patch in the same feature band | conservative default |
latestFeature | newest feature band in the same major.minor | most repositories |
latestMinor | newest minor in the same major | apps that track minor releases |
latestMajor | newest installed SDK | scratch projects, tools |
patch (default) | same feature band | inherits the strict behaviour |
| Symptom | Real cause | Fix |
|---|---|---|
A compatible .NET SDK was not found | global.json too strict | rollForward or an exact installed version |
dotnet --list-sdks works, --version fails | selection failed after listing | same as above |
NETSDK1045 targeting a newer framework | older SDK selected | install the newer SDK or retarget |
SDK 'Microsoft.NET.Sdk' specified could not be found | SDK resolver or NuGet feed | check msbuild-sdks, feeds, network |
| Works locally, fails in CI | different global.json in a parent folder | print the path from the error |
MSB4236 in Visual Studio only | VS ships one SDK copy | align 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.
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.jsonPrefer 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:
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 /appThat 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:
<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.jsonas 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;
latestFeatureis the durable form. - Setting
dotnet-versionin CI and ignoringglobal.json. Two pins, one of which lies. - Assuming
dotnet --versionreflects the project. It reports the selected SDK for the current directory and its parents. - Confusing
NETSDK1045with SDK resolution. One is about the target framework, the other about the requested SDK. - Copying a
global.jsonbetween repositories. TherollForwardthat 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 documentationThe C# documentation that defines the behaviour this guide explains.
Try matching browser tools
All toolsSmall utilities that fit C# work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related C# guides
All C# guidesC# await vs Task.Result: Avoid Blocking Async Code
c# await vs task result: Understand the difference between await and Task.Result in C#, why blocking on async tasks can cause deadlocks, and when it's acceptable.
EF Core: A second operation was started on this context instance
A DbContext is not thread-safe. Sequence the work, split it across factories, and stop capturing scoped contexts in background tasks.
CS8618: Non-nullable property must contain a non-null value
Nullable reference types caught a promise the constructor does not keep. Choose required, a constructor parameter, an honest string? or a documented null-forgiving default.
CS0219: The Variable Is Assigned but Its Value Is Never Used
Roslyn reports CS0219 only for locals whose assigned value is dead and side-effect free. How to tell a leftover from a forgotten return, and where to suppress it.
More in C#
All C# guidesThe guides filed next to this one in C#, in library order.