Error reporting

April 3, 2026 ยท View on GitHub

In order to get the most context for fatal errors we need to have Debug information correcty installed either alongside the vkQuake executable, or in a place where it can be found for post-mortem analysis:

  • Windows MSVC : Debug information is in the vkQuake.pdb file:

    • Using vkQuake-Installer-windows_x64-N.NN.N.exe : Automatically installs the .pdb file at the right place.
    • Using vkQuake-N.NN.N_windows_x64.zip : put the vkQuake.pdb file at the same place as the vkQuake.exe file.

  • Windows MSYS2 for either x64 or arm64 : Debug information is already built-in the vkQuake.exe file.

  • Linux :

    • Using the Appimage build: the archive contains vkquake.debuginfo that will be used for post-mortem analysis.
    • Using either Meson or Makefile builds : Debug information is already built-in the vkquake executable.

  • MacOS :

    • vkquake.dSYM directory contains the Debug information that will be used for post-mortem analysis, and should be put at the same place where the vkquake exeutable is.

Extracting file+line information from in-game vkQuake fatal errors :

Examples:

Windows MSVC

Error reporting is directly built-in in the game : Users can report screenshots of either Host_Error console errors or Quake Error dialogs.

Linux, MacOS, or Windows MSYS2 (x64 or ARM64)

Host_Error and Quake Error dialogs only report raw stack traces with minimal context, often limited to function names in the best of cases. In order to get file+line information Users will need to run some external tools.

STACK TRACE
0x100003f4d 0x100003f01 0x100003ed0 0x100003ea0 0x7fff2035a3d5

Run:

addr2line -e vkquake 0x16a8a8 0x93267 0x165735 0x165839 0x1669dd 0x166ea0 0x936ed

STACK TRACE
0 : ./vkquake(+0x16a8a8) [0x588582e618a8]
1 : ./vkquake(+0x93267) [0x588582d8a267]
2 : ./vkquake(+0x165735) [0x588582e5c735]
3 : ./vkquake(+0x165839) [0x588582e5c839]
4 : ./vkquake(+0x1669dd) [0x588582e5d9dd]
5 : ./vkquake(+0x166ea0) [0x588582e5dea0]
6 : ./vkquake(+0x936ed) [0x588582d8a6ed]

Run:

# Using relative addresses: 
addr2line -f -e [VKQUAKEBEBUG] 0x16a8a8 0x93267 0x165735 0x165839 0x1669dd 0x166ea0 0x936ed

or Run:

# Using absolute addresses: 
addr2line -f -e [VKQUAKEBEBUG] 0x588582e618a8 0x588582d8a267 0x588582e5c735 0x588582e5c839 0x588582e5d9dd 0x588582e5dea0 0x588582d8a6ed

Use whatever works best, where [VKQUAKEBEBUG] is the vkQuake executable if built with either Meson or Makefile, or vkquake.debuginfo for Appimage.

STACK TRACE
0x100003f4d 0x100003f01 0x100003ed0 0x100003ea0 0x7fff2035a3d5
0 : 0   vkquake                 0x0000000100003f4d Sys_StackTrace + 77
1 : 1   vkquake                 0x0000000100003f01 level3 + 17
2 : 2   vkquake                 0x0000000100003ed0 level2 + 16
3 : 3   vkquake                 0x0000000100003ea0 level1 + 16
4 : 4   libdyld.dylib           0x00007fff2035a3d5 start + 1

Run:

# Pass the first line :
atos -o vkquake 0x100003f4d 0x100003f01 0x100003ed0 0x100003ea0 0x7fff2035a3d5

As a result of running either addr2line or atos we get file+line trace information looking like this :

sys_sdl_win.c:461
sys_sdl_win.c:278
wad.c:82
host.c:1115
main_sdl.c:112
SDL_windows_main.c:?

That can be reported to vkQuake maintainers.