Skip to content

Commit b50ba41

Browse files
elinor-fungelinor-fung
authored
Add basic page for troubleshooting app launch failures (#28805)
1 parent ea7d55d commit b50ba41

File tree

2 files changed

+160
-0
lines changed

2 files changed

+160
-0
lines changed

‎docs/core/runtime-discovery/troubleshoot-app-launch.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
title: Troubleshoot app launch failures
3+
description: Learn about common reasons for app launch failures and possible solutions.
4+
ms.topic: troubleshooting
5+
ms.date: 03/24/2022
6+
zone_pivot_groups: operating-systems-set-one
7+
---
8+
9+
# Troubleshoot app launch failures
10+
11+
This article describes some common reasons and possible solutions for application launch failures.
12+
13+
## Required framework not found
14+
15+
[Framework-dependent applications](../deploying/index.md#publish-framework-dependent) rely on a .NET installation on your machine. If a required framework is not found or is not compatible with the required version, the application will fail to launch with a message similar to:
16+
17+
::: zone pivot="os-windows"
18+
19+
```console
20+
You must install or update .NET to run this application.
21+
22+
App: C:\repos\myapp\myapp.exe
23+
Architecture: x64
24+
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
25+
.NET location: C:\Program Files\dotnet\
26+
27+
The following frameworks were found:
28+
6.0.2 at [c:\Program Files\dotnet\shared\Microsoft.NETCore.App]
29+
```
30+
31+
::: zone-end
32+
33+
::: zone pivot="os-linux"
34+
35+
```bash
36+
You must install or update .NET to run this application.
37+
38+
App: /home/user/repos/myapp/myapp
39+
Architecture: x64
40+
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
41+
.NET location: /usr/share/dotnet/
42+
43+
The following frameworks were found:
44+
6.0.2 at [/usr/share/dotnet/shared/Microsoft.NETCore.App]
45+
```
46+
47+
::: zone-end
48+
49+
::: zone pivot="os-macos"
50+
51+
```bash
52+
You must install or update .NET to run this application.
53+
54+
App: /home/user/repos/myapp/myapp
55+
Architecture: x64
56+
Framework: 'Microsoft.NETCore.App', version '5.0.15' (x64)
57+
.NET location: /usr/local/share/dotnet/
58+
59+
The following frameworks were found:
60+
6.0.2 at [/usr/local/share/dotnet/shared/Microsoft.NETCore.App]
61+
```
62+
63+
::: zone-end
64+
65+
The error indicates the name, version, and architecture of the missing framework and the location at which it is expected to be installed. To run the application, you can [install a compatible framework](#install-a-compatible-framework) at the specified ".NET location". If the application is targeting a lower version than one you have installed and you would like to run it on a higher version, you can also [configure roll-forward behavior](#configure-roll-forward-behavior) for the application.
66+
67+
### Install a compatible framework
68+
69+
The error message includes a link to download the missing framework. You can follow this link to get the appropriate download page. Alternately, the [.NET downloads](https://dotnet.microsoft.com/download/dotnet) page offers all available versions of .NET. Select the version matching the one listed in the error message.
70+
71+
Every version of .NET offers three different runtime downloads. The following table shows the frameworks that each contains.
72+
73+
| Download name | Included frameworks |
74+
| -------------------- | ------------------- |
75+
| ASP.NET Core Runtime | Microsoft.NETCore.App<br/>Microsoft.AspNetCore.App |
76+
| .NET Desktop Runtime | Microsoft.NETCore.App<br/>Microsoft.WindowsDesktop.App |
77+
| .NET Runtime | Microsoft.NETCore.App |
78+
79+
To install a compatible framework, on the download page for the required .NET version, find a runtime download containing the missing framework. Once you have found the appropriate runtime download, you can then either install it using an [installer](#run-an-installer) or [download the binaries](#download-binaries) and extract them to the desired location.
80+
81+
#### Run an installer
82+
83+
If your existing installation of .NET was installed through an installer or package manager, then also installing the required framework through an installer or package manager is likely the simpler option. Otherwise, you can [download binaries](#download-binaries) instead of using an installer.
84+
85+
In most cases, when the application that failed to launch is using such an installation, the ".NET location" in the error message points to:
86+
::: zone pivot="os-windows"
87+
`%ProgramFiles%\dotnet`
88+
::: zone-end
89+
::: zone pivot="os-linux"
90+
`/usr/share/dotnet/`
91+
::: zone-end
92+
::: zone pivot="os-macos"
93+
`/usr/local/share/dotnet/`
94+
::: zone-end
95+
96+
::: zone pivot="os-windows,os-macos"
97+
From the **Installers** column of the runtime download, download the installer matching the required architecture. Run the downloaded installer.
98+
::: zone-end
99+
::: zone pivot="os-linux"
100+
Different Linux distributions provide .NET through different package managers. See [Install .NET on Linux](../install/linux.md) for details. Note that preview versions of .NET are not available through package managers.
101+
::: zone-end
102+
103+
#### Download binaries
104+
105+
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.
106+
107+
::: zone pivot="os-windows"
108+
For more details on manual installation, see [Install .NET on Windows](../install/windows.md#download-and-manually-install)
109+
::: zone-end
110+
111+
::: zone pivot="os-linux"
112+
For more details on manual installation, see [Install .NET on Linux](../install/linux.md#manual-installation)
113+
::: zone-end
114+
115+
::: zone pivot="os-macos"
116+
For more details on manual installation, see [Install .NET on macOS](../install/macos.md#download-and-manually-install)
117+
::: zone-end
118+
119+
### Configure roll-forward behavior
120+
121+
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.
122+
123+
When running the application, you can specify the [`--roll-forward` command line option](../tools/dotnet.md#runtime-options) or set the [`DOTNET_ROLL_FORWARD` environment variable](../tools/dotnet-environment-variables.md#dotnet_roll_forward).
124+
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 details, see [Framework-dependent apps roll-forward](../versions/selection.md#framework-dependent-apps-roll-forward).
125+
126+
> [!NOTE]
127+
> 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.
128+
129+
::: zone pivot="os-windows"
130+
131+
## Breaking changes
132+
133+
### Multi-level lookup disabled for .NET 7 and later
134+
135+
On Windows, before .NET 7, the application could search for frameworks in multiple [install locations](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md).
136+
137+
1. Subdirectories relative to:
138+
139+
- `dotnet` executable when running the application through `dotnet`
140+
- `DOTNET_ROOT` environment variable (if set) when running the application through its executable (`apphost`)
141+
142+
2. Globally registered install location (if set) in `HKLM\SOFTWARE\dotnet\Setup\InstalledVersions\<arch>\InstallLocation`.
143+
3. Default install location of `%ProgramFiles%\dotnet` (or `%ProgramFiles(x86)%\dotnet` for 32-bit processes on 64-bit Windows).
144+
145+
This multi-level lookup behavior was enabled by default but could be disabled by setting the environment variable `DOTNET_MULTILEVEL_LOOKUP=0`.
146+
147+
For applications targeting .NET 7 and later, multi-level lookup is completely disabled and only one location&mdash;the first location where a .NET installation is found&mdash;is searched. When running an application through `dotnet`, frameworks are only searched for in subdirectories relative to `dotnet`. When running an application through its executable (`apphost`), frameworks are only searched for in the first of the above locations where .NET is found.
148+
149+
For more details, see [Disable multi-level lookup by default](https://github.com/dotnet/designs/blob/main/accepted/2022/disable-multi-level-lookup-by-default.md).
150+
151+
::: zone-end
152+
153+
## See also
154+
155+
- [Install .NET](../install/index.yml)
156+
- [.NET install locations](https://github.com/dotnet/designs/blob/main/accepted/2020/install-locations.md)
157+
- [Check installed .NET versions](../install/how-to-detect-installed-versions.md)
158+
- [Framework-dependent applications](../deploying/index.md#publish-framework-dependent)

‎docs/fundamentals/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1657,6 +1657,8 @@ items:
16571657
href: ../core/runtime-config/networking.md
16581658
- name: Threading settings
16591659
href: ../core/runtime-config/threading.md
1660+
- name: Troubleshoot app launch failures
1661+
href: ../core/runtime-discovery/troubleshoot-app-launch.md
16601662
- name: Deployment models
16611663
items:
16621664
- name: Overview

0 commit comments

Comments
 (0)