When your game crashes, Unreal Engine creates a crash report, which it can send to the Crash Report Client. The Crash Report Client is an application that prompts users to provide optional comments and submit the crash report to Epic Games. You can customize the Crash Report Client packaged with your game to send crash report data to your own server to help with debugging your games.
This guide provides:
- An overview of crash reports and their contents.
- Information on where to find crash reports on your local machine.
- Config variable reference and project settings for crash reporting.
- How to modify and configure the crash reporter client for your own packaged applications.
- Recommendations for crash report services you can use to receive crash reports on a remote server.
Crash Reports
A crash report contains:
- A unique random crash identifier, called crash guid.
- Information about the error, such as the type (crash, assert, ensure, etc.), or the callstacks of the crashing thread and all other threads.
- System information for the machine and application context information such as build configuration.
- The log output at the moment of the crash. This can be device runtime logs or project editor logs.
- Additional context provided by the game using key/value pairs.
- Any additional comments provided by the user through the crash report client.
The following is an example of a crash report as viewed in the Crash Report Client:

Where To Find Local Crash Reports
Crash reports from the editor are stored on your local machine in your project’s Saved/Crashes
folder.
Alternatively, you can find crash reports on a user’s local machine in C:\Users[Your Windows Username]\AppData\Local[Project Name]\Saved\Crashes
.
Common Causes of Crashes in Unreal Engine
The following are the most common causes of crash reports that you will encounter. Each of these starts the Crash Reporter client with a message above the callstack giving details about the type of crash encountered.
Crash Source | Description | Example Image (Click to Enlarge) |
---|---|---|
Crash | Something has happened that the program can’t handle, so it shuts down. Reasons crashes occur include:
|
|
Assert | Caused by an assert statement that a developer put in the code to purposefully crash the program based on a certain condition. This is useful for checking something that you can predict will cause problems later during runtime, giving you an opportunity to catch it early. For example:
For more information about asserts in Unreal Engine, see the documentation page on asserts. |
|
Ensure | Ensures check for a certain condition, but do NOT crash if they resolve false. Instead, they produce a message to the Output Log and send a report to the Crash Reporter in unattended mode. These are useful for something you want to monitor, but not necessarily crash execution for. For example:
For more information about Ensures in Unreal Engine, see the documentation page on asserts. |
Ensures are meant as a development tool only, and are usually disabled in Test and Shipping build configurations. We recommend that you always publish a game to end consumers using the Shipping configuration. Distributing Development or Debugging builds can result in sending Epic Games unattended crash reports from your users if you haven’t modified the Crash Reporter Client.
Add Custom Context to Crash Reports
In addition to the standard information added to a crash report, it is also possible for game projects to add their own custom context, called game data. This could be information about the game mode, the player’s location in the world, or other game state information vital for investigating bugs. The data is added using key/value pairs and using the FPlatformCrashContext::SetGameData
function.
GenericPlatformCrashContext.h
/** Updates (or adds if not already present) arbitrary game data to the crash context (will remove the key if passed an empty string) */
CORE_API static void SetGameData(const FString& Key, const FString& Value);
Note that custom context is set before the error occurs. When a crash report is collected, the current state of the game data values is captured and written to the report.
As an example, whenever your game enters a new game mode call:
MyGameMode.cpp
void OnEnterMyGameMode()
{
FPlatformCrashContext::SetGameData(TEXT("GameMode"), TEXT("MyGameModeName"));
}
void OnExitMyGameMode()
{
FPlatformCrashContext::SetGameData(TEXT("GameMode"), FString());
}
A crash during that game mode will contain the following XMLdata:
CrashContext.runtime-xml
<GameData>
<GameMode>MyGameModeName</GameMode>
</GameData>
Crash Reporter Infrastructure
The crash report infrastructure for UE consists of the following components:
-
A Crash Report Client on the user’s machine, distributed with builds of the editor or your game. The Crash Report Client sends crash dump info to your endpoint.
-
A server with applications and components that manage, filter, and store crash reports.
The sections below detail each of these components and how to set them up for your own organization.
Crash Reporter Client
The Crash Reporter Client is a separate program that is used with both editor builds and optionally packaged with runtime builds on users’ machines. When either the editor or the packaged application crashes, the engine generates a crash report, then launches the Crash Reporter Client if available. If the Crash Reporter is not in unattended mode, it displays a window with the crash data and prompts users to send or opt out of sending the report.
Package the Crash Reporter Client With Your Game
By default, the Crash Reporter Client is not included with packaged games. To add it to your packaged builds:
-
In Unreal Editor, open Project Settings and navigate to Project > Packaging.
-
Unfold the Advanced dropdown.
-
Enable the Include Crash Reporter setting.
Alternatively, you can add IncludeCrashReporter=True
to your project’s Config/DefaultGame.ini
file.
DefaultGame.ini
[/Script/UnrealEd.ProjectPackagingSettings]
IncludeCrashReporter=True
Configure Automatic Crash Reports
The following config variables decide whether or not the crash reporter should automatically send crash reports to the server. You can configure these in any Engine.ini
file under the [CrashReportClient]
category.
Config Variable | Description |
---|---|
bAgreeToCrashUpload |
Controls whether or not the Crash Report Client should automatically send in crash events. This variable is only used for Linux builds. This defaults to false on Windows and Mac builds, but true on Linux builds. |
bSendUnattendedBugReports |
Controls whether or not to send in crash events unattended. If enabled, the Crash Report Client will skip displaying to the user and automatically send crash events to the server. This variable functions on all platforms, and defaults to true . |
DefaultEngine.ini
[CrashReportClient]
bAgreeToCrashUpload=false
bSendUnattendedBugReports=false
In UE 5.3.2 and earlier, due to a bug, bSendUnattendedCrashReports
did not work correctly on runtime builds packaged with the crash reporter. When set to false, the crash reporter would still automatically send reports on Ensures to Epic Games. This issue will be fixed in UE 5.4.
Configure the Crash Reporter Client
You can customize the Crash Reporter Client to send crash events to a server of your choice. To customize the Crash Reporter:
-
Open your Unreal Engine install directory.
-
Navigate to Engine/Programs/CrashReportClient/Config
-
Open the
DefaultEngine.ini
file.
This config file includes all variables used for configuring the Crash Reporter.
DefaultEngine.ini (Programs/CrashReportClient)
[CrashReportClient]
DataRouterUrl="https://datarouter.ol.epicgames.com/datarouter/api/v1/public/data"
bAllowToBeContacted=true
bSendLogFile=true
CanSendWhenUIFailedToInitialize=true
UIInitRetryCount=10
UIInitRetryInterval=2.0
Change the URL to Send Crash Reports To
To send crash reports to your own organization, change the DataRouterURL
variable to the URL of your own crash report server. Refer to the Crash Report Server section below for more information about how to set up this endpoint.
Config Variable Reference
The Crash Reporter Client’s config variables are as follows:
Config Variable | Default Value | Description |
---|---|---|
DataRouterUrl | https://datarouter.ol.epicgames.com/datarouter/api/v1/public/data | A URL pointing to your crash report server. |
bAllowToBeContacted | true | Default state of the "Allow to be contacted" option in the dialog. |
bSendLogFile | true | Controls whether the Crash Report Client should send the log file associated with the crash. |
CanSendWhenUIFailedToInitialize | true | If the Crash Report Client fails to initialize its UI, this controls whether or not to automatically send the crash report. |
UIInitRetryCount | 10 | Number of times to retry opening the Crash Report Client window before automatically sending a crash report. |
UIInitRetryInterval | 2 | Number of seconds between retry attempts. |
Editor builds always include the Crash Report Client, but including it in packaged builds is optional.
Crash Report Server
To make the most of the crash reporter, you need to set up a server that can receive remote users’ crash reports and symbolicate them. UE does not include such a component with its source code or binaries. However, using the source code for the Crash Report Client can give you a starting point to create your own custom solution. There are also several third-party crash report services that you can deploy.
The following crash report services are commonly used within the UE community. Each one has documentation for integrating them with UE’s crash reporter: