dotnet "A compatible .NET SDK was not found" in CI

By Kaveh Alemi·Latchkey

The runner has no usable .NET SDK on PATH - either none is installed, only a runtime is present, or the host cannot find one. dotnet build cannot proceed without an SDK.

What this error means

A dotnet command fails because there is no compatible SDK, or the shell reports dotnet: command not found. The build never starts because there is no SDK to drive it.

Terminal

It was not possible to find any compatible installed .NET SDKs.
Install a .NET SDK from https://aka.ms/dotnet/download
# or
bash: dotnet: command not found

Diagnose it: SDK version and restore

Terminal

dotnet --info
cat global.json 2>/dev/null
dotnet restore --verbosity normal
dotnet build --no-restore

Common causes

No SDK installed on the runner

A minimal image may ship only the .NET runtime (enough to run apps) but not the SDK needed to build them, or nothing at all.

dotnet is not on PATH

The SDK is installed in a non-standard location and its directory was never added to PATH, so the shell cannot find the dotnet binary.

How to fix it

Install the SDK with setup-dotnet

Pin and install a known SDK version so the runner always has one.

.github/workflows/ci.yml

- uses: actions/setup-dotnet@v4
  with:
    dotnet-version: '8.0.x'
- run: dotnet --info

Use the official SDK image in containers

For container builds, base on the SDK image (not the runtime image) so build tooling is present.

Dockerfile

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet build

Verify the install and PATH

Run dotnet --info and dotnet --list-sdks to confirm an SDK is visible.
If dotnet is missing, add its install directory to PATH.
Distinguish runtime-only images (dotnet/runtime, dotnet/aspnet) from SDK images.

How to prevent it

Always install the SDK explicitly in CI rather than relying on the image default.
Use dotnet/sdk images for build stages and runtime images only for the final stage.
Add a dotnet --info assertion early in the job.

Frequently asked questions

What causes dotnet "A compatible .NET SDK was not found" in CI?

There are 2 common causes: no sdk installed on the runner and dotnet is not on path. A minimal image may ship only the .NET runtime (enough to run apps) but not the SDK needed to build them, or nothing at all.

How do I fix dotnet "A compatible .NET SDK was not found" in CI?

There are 3 fixes depending on which cause you have: install the sdk with setup-dotnet, use the official sdk image in containers, and verify the install and path. Work through them in order, since the first is the most common.

What does dotnet "A compatible .NET SDK was not found" in CI actually mean?

A dotnet command fails because there is no compatible SDK, or the shell reports dotnet: command not found.

How do I stop dotnet "A compatible .NET SDK was not found" in CI happening again?

Always install the SDK explicitly in CI rather than relying on the image default. The prevention section lists 3 changes that keep it from recurring.