Edit

Troubleshoot app launch failures

  • Article

This article describes some common reasons and possible solutions for application launch failures. It relates to framework-dependent applications, which rely on a .NET installation on your machine.

If you already know which .NET version you need, you can download it from .NET downloads.

.NET installation not found

If a .NET installation isn't found, the application fails to launch with a message similar to:

You must install .NET to run this application.

App: C:\repos\myapp\myapp.exe
Architecture: x64
Host version: 7.0.0
.NET location: Not found

You must install .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Host version: 7.0.0
.NET location: Not found

This may be due to a package mix-up.

Global installs are registered in the following location: /etc/dotnet/install_location. For more information, see install locations.

You must install .NET to run this application.

App: /home/user/repos/myapp/myapp
Architecture: x64
Host version: 7.0.0
.NET location: Not found

Global installs are registered in the following location: /etc/dotnet/install_location. For more information, see install locations.

The error message includes a link to download .NET. You can follow that link to get to the appropriate download page. You can also pick the .NET version (specified by Host version) from .NET downloads.

On the download page for the required .NET version, find the .NET Runtime download that matches the architecture listed in the error message. You can then install it by downloading and running an Installer.

.NET is available through various Linux package managers. For more information, see Install .NET on Linux. (Preview versions of .NET aren't typically available through package managers.)

You need to install the .NET Runtime package for the appropriate version, like dotnet-runtime6.

Alternatively, on the download page for the required .NET version, you can download Binaries for the specified architecture.

Required framework not found

If a required framework or compatible version isn't found, the application fails to launch with a message similar to:

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

App: C:\repos\myapp\myapp.exe
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: C:\Program Files\dotnet\

The following frameworks were found:
  6.0.2 at [c:\Program Files\dotnet\shared\Microsoft.NETCore.App]

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

App: /home/user/repos/myapp/myapp
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: /usr/share/dotnet/

The following frameworks were found:
  6.0.2 at [/usr/share/dotnet/shared/Microsoft.NETCore.App]

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

App: /home/user/repos/myapp/myapp
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
.NET location: /usr/local/share/dotnet/

The following frameworks were found:
  6.0.2 at [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]

The error indicates the name, version, and architecture of the missing framework and the location at which it's expected to be installed. To run the application, you can install a compatible runtime at the specified ".NET location". If the application targets a lower version than one you have installed and you'd like to run it on a higher version, you can also configure roll-forward behavior for the application.

Install a compatible runtime

The error message includes a link to download the missing framework. You can follow this link to get to the appropriate download page.

Alternately, you can download a runtime from the .NET downloads page. There are multiple .NET runtime downloads.

The following table shows the frameworks that each runtime contains.

Runtime download Included frameworks
ASP.NET Core Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
.NET Desktop Runtime Microsoft.NETCore.App
Microsoft.WindowsDesktop.App
.NET Runtime Microsoft.NETCore.App
Runtime download Included frameworks
ASP.NET Core Runtime Microsoft.NETCore.App
Microsoft.AspNetCore.App
.NET Runtime Microsoft.NETCore.App

Select a runtime download that contains the missing framework, and then install it.

On the download page for the required .NET version, find the runtime download that matches the architecture listed in the error message. You likely want to download an Installer.

.NET is available through various Linux package managers. See Install .NET on Linux for details. (Preview versions of .NET aren't typically available through package managers.)

You need to install the .NET runtime package for the appropriate version, like dotnet-runtime6 or dotnet-aspnet6.

Alternatively, on the download page for the required .NET version, you can download Binaries for the specified architecture.

In most cases, when the application that failed to launch is using such an installation, the ".NET location" in the error message points to:

%ProgramFiles%\dotnet

/usr/share/dotnet/

/usr/local/share/dotnet/

Other options

There are other installation and workaround options to consider.

Run the dotnet-install script

Download the dotnet-install script for your operating system. Run the script with options based on the information in the error message. The dotnet-install script reference page shows all available options.

Launch PowerShell and run:

dotnet-install.ps1 -Architecture <architecture> -InstallDir <directory> -Runtime <runtime> -Version <version>

For example, the error message in the previous section would correspond to:

dotnet-install.ps1 -Architecture x64 -InstallDir "C:\Program Files\dotnet\" -Runtime dotnet -Version 5.0.15

If you encounter an error stating that running scripts is disabled, you may need to set the execution policy to allow the script to run:

Set-ExecutionPolicy Bypass -Scope Process

For more information on installation using the script, see Install with PowerShell automation.

./dotnet-install.sh --architecture <architecture> --install-dir <directory> --runtime <runtime> --version <version>

For example, the error message in the previous section would correspond to:

./dotnet-install.sh --architecture x64 --install-dir /usr/share/dotnet/ --runtime dotnet --version 5.0.15

For more information on installation using the script, see Scripted install.

./dotnet-install.sh --architecture <architecture> --install-dir <directory> --runtime <runtime> --version <version>

For example, the error message in the previous section would correspond to:

./dotnet-install.sh --architecture x64 --install-dir /usr/local/share/dotnet/ --runtime dotnet --version 5.0.15

For more information on installation using the script, see Install with bash automation.

Download binaries

You can download a binary archive of .NET from the download page. From the Binaries column of the runtime download, download the binary release matching the required architecture. Extract the downloaded archive to the ".NET location" specified in the error message.

For more information about manual installation, see Install .NET on Windows

For more information about manual installation, see Install .NET on Linux

For more information about manual installation, see Install .NET on macOS

Configure roll-forward behavior

If you already have a higher version of the required framework installed, you can make the application run on that higher version by configuring its roll-forward behavior.

When running the application, you can specify the --roll-forward command line option or set the DOTNET_ROLL_FORWARD environment variable. By default, an application requires a framework that matches the same major version that the application targets, but can use a higher minor or patch version. However, application developers may have specified a different behavior. For more information, see Framework-dependent apps roll-forward.

Note

Since using this option lets the application run on a different framework version than the one for which it was designed, it may result in unintended behavior due to changes between versions of a framework.

Breaking changes

Multi-level lookup disabled for .NET 7 and later

On Windows, before .NET 7, the application could search for frameworks in multiple install locations.

  1. Subdirectories relative to:

    • dotnet executable when running the application through dotnet.
    • DOTNET_ROOT environment variable (if set) when running the application through its executable (apphost).

  2. Globally registered install location (if set) in HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation.

  3. Default install location of %ProgramFiles%\dotnet (or %ProgramFiles(x86)%\dotnet for 32-bit processes on 64-bit Windows).

This multi-level lookup behavior was enabled by default but could be disabled by setting the environment variable DOTNET_MULTILEVEL_LOOKUP=0.

For applications targeting .NET 7 and later, multi-level lookup is completely disabled and only one location—the first location where a .NET installation is found—is searched. When an application is run through dotnet, frameworks are only searched for in subdirectories relative to dotnet. When an application is run through its executable (apphost), frameworks are only searched for in the first of the previously listed locations where .NET is found.

For more information, see Multi-level lookup is disabled.

See also