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

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

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.