Framework 'Microsoft.NETCore.App' version not found at runtime in CI

The build produced an app that needs a specific shared runtime, but the runner only has the SDK/runtime for a different version when it tries to run or test it. This is a runtime (not build) problem - the host cannot find a matching Microsoft.NETCore.App.

What this error means

Running or dotnet test fails with "You must install or update .NET ... Framework 'Microsoft.NETCore.App', version X was not found", listing the runtimes that are present. Tied to installed runtimes vs the app's target.

You must install or update .NET to run this application.
App: /repo/bin/Release/net8.0/App.dll
Framework: 'Microsoft.NETCore.App', version '8.0.0' (x64) was not found.

Common causes

The matching runtime is not installed

The runner has an SDK/runtime for a different major version than the published app targets, so the host cannot start it.

A separate run job lost the SDK setup

A later job (test, deploy) runs on an environment where the setup-dotnet step was not applied, so the runtime is absent.

How to fix it

Install the matching runtime/SDK before running

1. Add setup-dotnet with the app's major version in the job that runs/tests it.
2. Confirm dotnet --list-runtimes shows the needed Microsoft.NETCore.App version.
3. Re-run.

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

Enable roll-forward or self-contained publish

1. Set rollForward so a newer installed runtime can host the app.
2. Or publish self-contained so the runtime ships with the app and no install is needed.
3. Re-run.

dotnet publish -c Release -r linux-x64 --self-contained true

How to prevent it

• Install the runtime in every job that runs or tests the app.
• Use roll-forward or self-contained publish for runtime portability.
• Verify dotnet --list-runtimes matches the app's target.

Related guides