Unreal Engine 5 Documentation has been moved to the Epic Developer Community

As of version 4.15.2, Unreal Engine supports NVIDIA's Aftermath C++ library for Windows-based developers, which provides additional data from NVIDIA GeForce-based GPUs after a crash occurs. This data contains crucial information about what the GPU was doing when the crash occurred, enabling you to track down what's happening with the GPU in your own projects.

Aftermath is a lightweight tool that is unobtrusive and reduces the performance footprint needed by some debugging tools. In fact, it's lightweight enough that it can even ship with finished games to provide the data you need from your customers' machines. Aftermath enables programmers to insert markers into their code that assist in tracking the root causes of crashes. This is now being used in the Unreal Engine Editor to track down and fix reported or captured issues.

For additional information and how to use it in your own project, visit NVIDIA's Aftermath documentation page.

Enabling NVIDIA Aftermath

If you're using Unreal Engine version 4.15.2, NVIDIA Aftermath is automatically enabled. You can use the following console command to set it in your ConsoleVariables.ini configuration file:

r.DX11NVAfterMathEnabled

If you're using Unreal Engine version 4.16 or later, NVIDIA Aftermath is automatically disabled. You can use the following console command to set it in your ConsoleVariables.ini configuration file:

r.GPUCrashDebugging=1

You can also enable it by passing the following argument to the command line:

-gpucrashdebugging

Logs

Once you've enabled NVIDIA Aftermath, you should see the following output in your log:

LogD3D11RHI: [Aftermath] Aftermath enabled and primed

You can access your log in Unreal Engine 4 by going to File Menu > Window > Developer Tools > Output Log or by opening the log text file from your project folder.

When a crash happens, the log will display something similar to the following:

LogD3D11RHI: Error: Result failed at X:[Project Folder]\Engine\Source\Runtime\Windows\D3D11RHI\Private\D3D11Viewport.cpp:290 with error DXGI_ERROR_DEVICE_REMOVED DXGI_ERROR_DEVICE_HUNG
LogRHI: Error: [Aftermath] Status: Timeout
LogRHI: Error: [Aftermath] GPU Stack Dump
LogRHI: Error: [Aftermath] 0: Frame2769
LogRHI: Error: [Aftermath] 1: FRAME
LogRHI: Error: [Aftermath] 2: Scene
LogRHI: Error: [Aftermath] 3: ComputeLightGrid
LogRHI: Error: [Aftermath] 4: Compact
LogRHI: Error: [Aftermath] GPU Stack Dump

In this particular example, the GPU has crashed and the resulting lines with the [Aftermath] preceeding indicate the status and where in the frame the problem is so that you can investigate what was the root cause.

Considerations

For an average project that has approximately 200 to 300 markers, Aftermath is fast enough, but slowdowns can happen when you have certain things like lots of per-object shadows that can increase its cost. For this reason, the feature is not enabled by default.