.NET in Docker: 'You must install or update .NET' for 'Microsoft.AspNetCore.App'

You must install or update .NET to run this application. with Framework: 'Microsoft.AspNetCore.App', version '10.0.0' (x64) means a web app was started where the .NET runtime exists but the ASP.NET Core runtime does not. In Docker that usually means the app runs on mcr.microsoft.com/dotnet/runtime instead of mcr.microsoft.com/dotnet/aspnet. Switch the image and it starts.

Run a web app on the aspnet image (in a Dockerfile, the final stage's FROM line). On a server, install the ASP.NET Core runtime, not only the .NET runtime. Publishing self-contained is the other way out: the app then carries both runtimes.

The error

You must install or update .NET to run this application.

App: /app/ApiLab.dll
Architecture: x64
Framework: 'Microsoft.AspNetCore.App', version '10.0.0' (x64)
.NET location: /usr/share/dotnet/

No frameworks were found.

Learn more:
https://aka.ms/dotnet/app-launch-failed

To install missing framework, download:
https://aka.ms/dotnet-core-applaunch?framework=Microsoft.AspNetCore.App&framework_version=10.0.0&arch=x64&rid=linux-x64&os=ubuntu.24.04

Why it happens

A framework-dependent web app does not carry its runtime. Its ApiLab.runtimeconfig.json names two shared frameworks, and the host must find both before it starts the app:

    "frameworks": [
      {
        "name": "Microsoft.NETCore.App",
        "version": "10.0.0"
      },
      {
        "name": "Microsoft.AspNetCore.App",
        "version": "10.0.0"
      }
    ],

The runtime image has only the first. dotnet --list-runtimes inside it printed one line, Microsoft.NETCore.App 10.0.13, while the aspnet image printed that line plus Microsoft.AspNetCore.App 10.0.13. When a framework is missing, the host lists the versions it found of that same framework, and there were none, hence "No frameworks were found." The exit code was 150. The version in the message is a minimum: the app asked for 10.0.0 and ran happily on 10.0.13.

The fix

docker run -d --name fix6-aspnet -p 127.0.0.1:15490:8080 -v ...\ApiLab\out:/app -w /app mcr.microsoft.com/dotnet/aspnet:10.0 dotnet ApiLab.dll
curl -s -i http://127.0.0.1:15490/
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: Fri, 23 Oct 2026 04:41:19 GMT
Server: Kestrel
Transfer-Encoding: chunked

Hello World!

The same published folder, unchanged, served its endpoint once the image had the ASP.NET Core runtime. The second route was also tested: dotnet publish -c Release -r linux-x64 --self-contained true produced an ApiLab executable that started on the plain runtime image and answered Hello World!, at the cost of a larger output folder: 341 files and 104.7 MB against 8 files and 0.1 MB. On an Ubuntu 24.04 server, the distribution's feed lists the package aspnetcore-runtime-10.0 (10.0.13 on the day of the test); installing it was not part of this test.

How it was reproduced

On Windows 11 with .NET SDK 10.0.402 and Docker 29.9.2: a minimal API from dotnet new web -n ApiLab, published with dotnet publish -c Release -r linux-x64 --self-contained false -o out. The folder was mounted into mcr.microsoft.com/dotnet/runtime:10.0, pulled for the test, and started with dotnet ApiLab.dll. The fix used the cached mcr.microsoft.com/dotnet/aspnet:10.0 on 127.0.0.1:15490. The container names are the test's own and were removed after each run.

Frequently asked

What is the difference between the dotnet runtime and aspnet Docker images?

The runtime image contains only Microsoft.NETCore.App. The aspnet image adds Microsoft.AspNetCore.App, which every ASP.NET Core app, including a minimal API, needs. Console apps run on either.

Why does my ASP.NET Core app say No frameworks were found?

The host lists the installed versions of the framework it is missing. If the machine has no ASP.NET Core runtime at all, that list is empty. Install the ASP.NET Core runtime or use the aspnet image.

Can I run an ASP.NET Core app on the dotnet runtime image?

Only if you publish it self-contained with dotnet publish -r linux-x64 --self-contained true, so the app carries the ASP.NET Core runtime itself. A framework-dependent build needs the aspnet image.

If the message names Microsoft.NETCore.App with an older major version instead, the runtime is there but too new; see You must install or update .NET to run this application (version 8.0.0). More decoded errors are in the Fixes category.