Skip to main content

Xbox consoles crash reporter integration guide

Last updated on November 10, 2026

Overview​

This guide shows you how to enable the AccelByte Development Toolkit (ADT) Crash Reporter for Xbox Series X|S (XSX) and Xbox One builds made with the Microsoft Game Development Kit (GDK), on devkits and on players' retail consoles.

When the game crashes, the ADT SDK saves the crash report on the console. The next time the game starts, the SDK sends the report to ADT, and the crash appears in ADT Web.

Prerequisites​

  1. ADT SDK integration

    Confirm the Windows version of the ADT SDK is already integrated. To learn how, refer to ADT SDK integration.

  2. Unreal Engine source code

    Make sure your Unreal Engine is built from source, not downloaded from the Epic Games Store. The Epic Games Store version doesn't support console development.

  3. ADT SDK and CLI versions

    • For devkits: any supported ADT SDK version.
    • For retail consoles: ADT SDK 2.34.4 or later and ADT CLI 2.31.1 or later.
  4. Xbox add-on

    a. In ADT Web, go to Game Settings > Game Integration.

    b. Under the Target Platform section, select Xbox One (GDK) or Xbox Series X.

    c. Download the required add-on from the ADT Download page.

Xbox add-on integration​

  1. Extract the downloaded add-on. This creates a folder named BlackBox-UE4SDK-x64-XSX-<SDKVersion>.

  2. Open the folder and copy the BlackBoxSDK directory.

  3. Paste the BlackBoxSDK directory into your game project's Plugins folder.

Enable the Xbox crash reporter​

After you create a version, follow these steps. To learn how to create a version, refer to Create versions and register builds.

  1. Register your Xbox builds

    Select the target platform:

    a. xboxonegdk for Xbox One builds.

    b. xsx for Xbox Series X|S builds.

    c. Run the following command to add a new build ID. The example uses xsx:

    .\BlackBoxCLI.exe build register --namespace <your_namespace> --smartbuild --platform-name xsx --platform-arch x64 --apikey <your_api_key> --game-project <game_project_path> --game-engine <game_engine_path>

    Xbox builds send crashes through the ADT SDK, not through a crash URL, so you don't need to run crash-url set.

    For a build that you release to players, also add --release-candidate. To learn more, refer to Live (retail) crash reporting.

  2. Modify the Unreal Engine (restricted)

    This step is restricted to ADT customers due to NDA compliance with Microsoft. Contact AccelByte support for detailed instructions.

Package and upload​

  1. Package your game

    a. Open the .uproject file.

    b. In the Unreal Engine Editor, select Platform > XSX > Package Project.

  2. Upload the program database (PDB) files

    After the cook completes, upload the PDB files with this command:

    .\BlackBoxCLI.exe upload --namespace <your_namespace> --game-archive <game_archive_path> --platform-name xsx --platform-arch x64 --apikey <your_api_key> --game-project <game_project_path> --game-engine <game_engine_path>
  3. Upload the binary files (for devkit testing through ADT Hub)

    To deploy the build to devkits through ADT Hub, upload the binary files:

    .\BlackBoxCLI.exe build upload-binaries --namespace <your_namespace> --game-archive <game_archive_path> --entry-point <the .xvc file for the game> --apikey <your_api_key> --game-project <game_project_path> --game-engine <game_engine_path>

Where crash reports are stored​

The SDK saves each crash report in a folder named xboxgdk_crash_<iso8601_time>, in the first available location:

  1. The game's Persistent Local Storage, if the game reserves it. Retail consoles need it.
  2. D:\, which is System Scratch on a devkit.

On the next launch, the SDK sends the stored reports to ADT. After a report is sent, the SDK deletes its folder. The SDK keeps at most five unsent reports, and each report can be up to 256 MB.

AspectOn a devkitOn a retail console
StoragePersistent Local Storage, or D:\ (System Scratch)Persistent Local Storage only
Crash videoYesNo
Deploy the buildADT Hub or the Microsoft GDK toolsMicrosoft Partner Center

Test on a devkit​

  1. Download and deploy the build

    a. Log in to ADT Hub. If it isn't installed, download it from ADT Web.

    b. Go to the Channels or Versions page to find your uploaded build.

    c. Click Download. When the download completes, the button changes to Deploy.

    d. Select your devkit and deploy the build. To learn how, refer to Connect DevKits to deploy builds.

  2. Trigger a crash

    a. Launch the game on the devkit, then intentionally crash it after it fully launches.

    b. Find the crash report folder xboxgdk_crash_<iso8601_time> in the storage location described in Where crash reports are stored.

  3. Verify the crash report upload

    a. Launch the game again to send the crash report to ADT.

    b. Check the crash in ADT Web under Crashes.

Live (retail) crash reporting​

This section covers Xbox only. For Windows, Linux, macOS, and PlayStation 5, refer to the Live (retail) crash reporting page.

Retail consoles have no D:\ drive. To get crashes from players' retail consoles, follow these steps in addition to the steps above. Make sure you use the ADT SDK and CLI versions listed in Prerequisites.

1. Save the crash dump to a retail-safe location (restricted)​

In Shipping builds, the engine must write the crash dump to a location that exists on retail consoles. This is a change to the engine's Xbox platform code, and it's restricted due to NDA compliance with Microsoft. Contact AccelByte support for the instructions.

This change is separate from the one in step 2 of Enable the Xbox crash reporter. Retail builds need both changes. You can ask support for both sets of instructions in one request.

2. Reserve Persistent Local Storage​

The SDK keeps crash reports in Persistent Local Storage until the next launch. Without it, crash reports from retail consoles are lost. Reserve 64 MB in one of these ways:

  • In Project Settings > Platforms > Xbox Series X|S > Features, set Persistent Local Storage (MB) to 64. If you ship on Xbox One, do the same under Xbox One.

  • Add the following to <Project>\Platforms\XSX\Config\XSXEngine.ini:

    [/Script/XSXPlatformEditor.XSXTargetSettings]
    PersistentLocalStorage=64
warning

If your game already uses Persistent Local Storage and about 64 MB of it is free, keep the current size. Increasing the size in a title update erases the existing storage on players' consoles.

3. Register and prepare the build as a release candidate​

To label crashes from this build as Players in ADT Web, register the build as a release candidate (RC), then prepare it before you package it:

.\BlackBoxCLI.exe build register --namespace <your_namespace> --smartbuild --platform-name xsx --platform-arch x64 --apikey <your_api_key> --game-project <game_project_path> --game-engine <game_engine_path> --release-candidate
.\BlackBoxCLI.exe build prepare --namespace <your_namespace> --apikey <your_api_key> --game-project <game_project_path> --game-engine <game_engine_path>

build prepare keeps the ADT SDK enabled and sets LiveBuild=true in Config/BlackBox.ini. The SDK then sends this build's crashes with the live flag.

important
  • ADT labels Xbox crashes by the build, not by the console. Crashes from an RC build that you prepared are labeled Players, even on a devkit. Crashes from any other build, including builds not registered as an RC, are labeled Internal, even on a retail console.
  • The label is set when you package the build. Setting the build to Live in ADT Web afterward doesn't change the label of Xbox crashes.

4. Package, upload symbols, and release​

Set the build configuration to Shipping before you package. Then package the game and upload the PDB files as described in Package and upload, and release the build through Microsoft Partner Center.

5. Confirm on a retail console​

  1. Install the build on a retail Xbox, then make the game crash.

  2. Launch the game again. The SDK sends the crash report during this launch.

  3. In the game log, look for these lines. R:\ is the Persistent Local Storage location that the console gives the game, which you reserved in step 2.

    LogBlackBox: [INFO] Crash storage: R:\
    LogBlackBox: [INFO] Successfully sent the crashbinary: R:/xboxgdk_crash_<time>
  4. In ADT Web, go to Crashes, set the Origin filter to Players, then check the crash.

info
  • The SDK sends Xbox crash reports the next time the game starts after a crash.
  • Crashes sent by the SDK count against the namespace's development daily crash limit, including crashes labeled Players. If the limit is reached, the report stays on the console and the SDK sends it on a later launch. To learn more, refer to Crash limit management.