Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A containerized ASP.NET Core app says the framework Microsoft.AspNetCore.App was not found

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

Short answer

The app asks for a shared framework the final image does not have. The plain runtime image holds only Microsoft.NETCore.App, so a web app needs the aspnet image, with the same major version as the SDK that built it. Read the framework and version in the message, then fix the FROM line of the last stage.

  • Applies to .NET 8, .NET 9, Docker Engine 28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the message: it names the framework and version the app wants, and lists what the image has. Then see which base image the last stage uses.

    grep -n "^FROM" Dockerfile
    docker run --rm --entrypoint dotnet my-app --info
  2. 2Match what you see, then jump to its fix

    1. 1The found list shows only Microsoft.NETCore.App, and the missing one is Microsoft.AspNetCore.App.The final stage uses the runtime image, not the aspnet imageFix
    2. 2The message asks for version 6.0.0 (or another number) while the image holds a different major version.The image tag is a different major version than the app targetsFix
    3. 3The .NET location in the message is not the install folder of the image, or the variable is set in the Dockerfile or compose file.DOTNET_ROOT points to the wrong placeFix

What does the error look like?

  • You must install or update .NET to run this application.
  • Framework: 'Microsoft.AspNetCore.App', version '6.0.0' (x64)
  • The following frameworks were found:

Cause 1 of 3

The final stage uses the runtime image, not the aspnet image

1Check

The mcr.microsoft.com/dotnet/runtime image contains only Microsoft.NETCore.App. ASP.NET Core apps also need Microsoft.AspNetCore.App, which the ASP.NET Core Runtime provides.

grep -n "dotnet/runtime" Dockerfile

2Fix

Use the aspnet image for the stage that runs the app. Microsoft's own tutorial uses it for the final stage.

FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /out

FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app
COPY --from=build /out .
ENTRYPOINT ["dotnet", "MyApp.dll"]

3Verify

The output now lists Microsoft.AspNetCore.App.

docker build -t my-app .
docker run --rm --entrypoint dotnet my-app --info

Confirmed by learn.microsoft.com

Did this fix it?

Cause 2 of 3

The image tag is a different major version than the app targets

1Check

By default an app needs a framework of the same major version it targets, and can use a higher minor or patch version. A net6.0 app does not start on a 9.0 image unless roll-forward is set.

grep -n "TargetFramework" *.csproj
grep -n "^FROM" Dockerfile

2Fix

Make the SDK tag and the aspnet tag match the TargetFramework. If you really want a newer runtime, retarget the project; roll-forward can run an app on a higher framework but may change behavior.

# csproj
<TargetFramework>net9.0</TargetFramework>

# Dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:9.0

3Verify

Rebuild and start the container.

docker build -t my-app . && docker run --rm my-app

Confirmed by learn.microsoft.com

Did this fix it?

Cause 3 of 3

DOTNET_ROOT points to the wrong place

1Check

When DOTNET_ROOT is set, .NET skips its default install location. A value left over from another image or a script makes the app look in a folder with no framework.

docker run --rm --entrypoint sh my-app -c 'echo $DOTNET_ROOT'

2Fix

Remove DOTNET_ROOT from the Dockerfile and compose file unless you installed .NET to a custom folder, and rebuild.

# delete lines like this from the Dockerfile or compose file
ENV DOTNET_ROOT=/some/old/path

3Verify

Start the container again.

docker run --rm my-app

Confirmed by learn.microsoft.com

Did this fix it?

How do I stop it coming back?

  • Use a multi-stage Dockerfile: sdk image to build, aspnet image to run, same version tag on both.
  • Change the TargetFramework and both image tags in one commit.
  • Run docker run --entrypoint dotnet <image> --info in CI after the build.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.