Debug Linux dumps
This article applies to: ✔️ .NET Core 3.0 SDK and later versions
Collect dumps on Linux
For frequently asked questions about dump collection, analysis, and other caveats, see Dumps: FAQ.
The two recommended ways of collecting dumps on Linux are:
Analyze dumps on Linux
After a dump is collected, it can be analyzed using the
dotnet-dump tool with the
dotnet-dump analyze command. This analysis step needs to be run on a machine that has the same architecture and Linux distro as the environment the dump was captured in.
dotnet-dump tool supports displaying information about .NET code, but is not useful for understanding code issues for other languages like C and C++.
Alternatively, LLDB can be used to analyze dumps on Linux, which allows analysis of both managed and native code. LLDB uses the SOS extension to debug managed code. The
dotnet-sos CLI tool can be used to install SOS, which has many useful commands for debugging managed code. In order to analyze .NET Core dumps, LLDB and SOS require the following .NET Core binaries from the environment the dump was created in:
- dotnet (the host used to launch the app)
In most cases, these binaries can be downloaded using the
dotnet-symbol tool. If the necessary binaries can't be downloaded with
dotnet-symbol (for example, if a private version of .NET Core built from source was in use), it may be necessary to copy the files listed above from the environment the dump was created in. If the files aren't located next to the dump file, you can use the LLDB/SOS command
setclrpath <path> to set the path they should be loaded from and
setsymbolserver -directory <path> to set the path to look in for symbol files.
Once the necessary files are available, the dump can be loaded in LLDB by specifying the dotnet host as the executable to debug:
lldb --core <dump-file> <host-program>
In the previous command,
<dump-file> is the path of the dump to analyze and
<host-program> is the native program that started the .NET Core application. This is typically the
dotnet binary unless the app is self-contained, in which case it is the name of the application without the .dll extension.
Once LLDB starts, it may be necessary to use the
setsymbolserver command to point at the correct symbol location (
setsymbolserver -ms to use Microsoft's symbol server or
setsymbolserver -directory <path> to specify a local path). To load native symbols, run
loadsymbols. At this point, you can use SOS commands to analyze the dump.
LLDB can be installed with the command
sudo apt-get install lldb
Analyze dumps on Windows
Dumps collected from a Linux machine can also be analyzed on a Windows machine using Visual Studio, Windbg, or the dotnet-dump tool. Both Visual Studio and Windbg can analyze native and managed code, while dotnet-dump only analyzes managed code.
Visual Studio version 16.8 and later allows you to open and analyze Linux dumps generated on .NET Core 3.1.7 or later.
- Visual Studio - See the Visual Studio dump debugging guide.
- Windbg - You can debug Linux dumps on windbg using the same instructions you would use to debug a Windows user-mode dump. Use the x64 version of windbg for dumps collected from a Linux x64 or Arm64 environment and the x86 version for dumps collected from a Linux x86 environment.
- dotnet-dump - View the dump using the dotnet-dump analyze command. Use the x64 version of dotnet-dump for dumps collected from a Linux x64 or Arm64 environment and the x86 version for dumps collected from a Linux x86 environment.
- dotnet-sos for more details on installing the SOS extension.
- dotnet-symbol for more details on installing and using the symbol download tool.
- .NET Core diagnostics repo for more details on debugging, including a useful FAQ.
- Installing LLDB for instructions on installing LLDB on Linux or Mac.
- Practice and troubleshoot on Linux for tutorial on debugging crash dumps on Linux