Skip to main content

Setting Up Backtrace for Unreal Engine

Add Backtrace to your Unreal Engine project to automatically detect and report native crashes that occur in your game.

Backtrace supports Unreal Engine's Crash Reporter, therefore installation of a Backtrace SDK is not required to capture crashes.

Features

The Backtrace Unreal plugin reports on the following types of errors:

  • Crashes - An end to the game play experience, where the game crashes or restarts.
  • Hangs (mobile only) - Errors that occur when a game or an app is non-responsive.
  • Out of memory crashes (mobile only) - Terminations of your game or app due to low memory conditions.

Supported Platforms

Supported PlatformsSupported Systems
MobileAndroid, iOS
PCWindows, MacOS, Linux
Game ConsolesPlayStation 4, PlayStation 5, Xbox One, Xbox Series X, Xbox Series S, Nintendo Switch, Steam Deck
note

For on-premise (self-hosted) users, the integration for Unreal Engine requires specific packages. For more information, contact support.

What You'll Need

  • A Backtrace account (log in or sign up for a free trial license).
  • Your subdomain name (used to connect to your Backtrace instance). For example, https://example-subdomain.sp.backtrace.io.
  • A Backtrace project and a submission token.

System Requirements

  • Unreal Engine version 4.16 to 5.2

Initialize the Backtrace Client

For Crashes in the Editor

  1. In the root directory for your Unreal Engine project, open the Config folder.

  2. Copy the DefaultEngine.ini file and paste it into the Engine > Config folder.

    note

    If the Engine folder doesn't exist at the root directory for your Unreal Engine project, create a new folder and name it Engine. Then in the Engine folder, create another folder and name it Config.

  3. Rename the file to UserEngine.ini.

  4. Open the UserEngine.ini file and add the following lines:

    [CrashReportClient]
    CrashReportClientVersion=1.0
    DataRouterUrl="https://unreal.backtrace.io/post/{subdomain}/{submission-token}"
  5. For the DataRouterUrl, provide the name of your subdomain and a submission token.

When your app or game crashes in the Unreal Editor, the Unreal Engine Crash Reporter dialog will appear and allow you to send the crash report to your Backtrace instance.

For Crashes in Packaged Builds

Enable the Crash Reporter

  1. In the Unreal Editor, go to Edit > Project Settings.
  2. In the Project Settings, search for "crash reporter".
  3. Under Packaging, enable Include Crash Reporter.Enable the Crash Reporter in the Unreal Editor.
note

If you're building from the command line, add the -crashreporter flag.

Configure the Crash Reporter

You can configure the crash reporter to be the default for all packaged builds or for a single packaged build.

To configure the crash reporter as the default for all packaged builds:

  1. In the root directory for your Unreal Engine project, open the Config folder.
  2. Copy the DefaultEngine.ini file and paste it into the following directory: [UNREAL_ENGINE]/UnrealEngine/Engine/Programs/CrashReportClient/Config
    note

    The directory could also be under C:/Program Files/Epic Games/UE_[version]. You can also search your system for 'CrashReportClient' to find it.

  3. Open the DefaultEngine.ini file and add the following lines:
    [CrashReportClient]
    CrashReportClientVersion=1.0
    DataRouterUrl="https://unreal.backtrace.io/post/{subdomain}/{submission-token}"
  4. For the DataRouterUrl, provide the name of your subdomain and a submission token.

To configure the crash reporter for a packaged build:

  1. In the root directory for your Unreal Engine project, open the Config folder.
  2. Copy the DefaultEngine.ini file and paste it into the following directory:
    • For Unreal Engine 4.25 and earlier: [BUILD_DIRECTORY]/WindowsNoEditor/Engine/Programs/CrashReportClient/Config/NoRedist
    • For Unreal Engine 4.26 and higher: [BUILD_DIRECTORY]/WindowsNoEditor/Engine/Restricted/NoRedist/Programs/CrashReportClient/Config
      note

      Create the subdirectories if they do not exist.

  3. Open the DefaultEngine.ini file and add the following lines:
    [CrashReportClient]
    CrashReportClientVersion=1.0
    DataRouterUrl="https://unreal.backtrace.io/post/{subdomain}/{submission-token}"
  4. For the DataRouterUrl, provide the name of your subdomain and a submission token.

Upload Debug Symbols

You must now ensure your build environment has been configured to generate debug symbols, which can then be uploaded to your Backtrace instance, a connected Symbol Server, an Amazon S3 bucket, or a Google Cloud storage bucket.

For information on how to generate symbols, see Symbolication.

Verify the Setup

At this point, you've installed and setup the Backtrace client to automatically capture crashes in your Unreal Engine game or app.

To test the integration, send a crash report to your Backtrace instance.

To crash your game when it starts, create a class called MyActor and reference a blueprint. The blueprint can be attached to the BeginPlay event.

The header file (which has the .h extension) contains the class definitions and functions, while the implementation of the class is defined by the .cpp file. For example:

  • MyActor.h:

    // Fill out your copyright notice in the Description page of Project Settings.

    #pragma once

    #include "CoreMinimal.h"
    #include "GameFramework/Actor.h"
    #include "GenericPlatform/GenericPlatformCrashContext.h"
    #include "MyActor.generated.h"

    UCLASS()
    class BACKTRACE_API AMyActor : public AActor
    {
    GENERATED_BODY()

    public:
    // Sets default values for this actor's properties
    AMyActor();

    protected:
    // Called when the game starts or when spawned
    virtual void BeginPlay() override;

    public:
    // Called every frame
    virtual void Tick(float DeltaTime) override;

    UFUNCTION(BlueprintCallable, Category = "Backtrace Tools")
    void DoCrashMe();

    };
  • MyActor.cpp:

    // Fill out your copyright notice in the Description page of Project Settings.


    #include "MyActor.h"

    // Sets default values
    AMyActor::AMyActor()
    {
    // Set this actor to call Tick() every frame. You can turn this off to improve performance if you don't need it.
    PrimaryActorTick.bCanEverTick = true;

    }

    // Called when the game starts or when spawned
    void AMyActor::BeginPlay()
    {
    Super::BeginPlay();
    {

    FGenericCrashContext::SetGameData(TEXT("BluePrintCallStack"), TEXT("BluePrintCallStackValue"));
    }

    }

    // Called every frame
    void AMyActor::Tick(float DeltaTime)
    {
    Super::Tick(DeltaTime);

    }

    void AMyActor::DoCrashMe()
    {

    UE_LOG(LogTemp, Fatal, TEXT("I crash and burn. Bye bye now"));

    }