Crash Reporting for C++ Games With Minidumps

A C++ game has no runtime safety net. A bad pointer, an out of bounds write, or a stack overflow in a shipped build does not raise a friendly exception with a message; it terminates the process and leaves the player staring at a closed window. To debug that, you need the machine state captured at the moment of the fault, and the standard way to capture it is a minidump. This post walks through installing crash handlers on Windows and Linux, writing minidumps, keeping symbols around, and turning the raw bytes into a stack trace you can actually read.

Why native crashes need minidumps

In a managed language a crash usually unwinds with a message and a stack you can log. C++ gives you none of that for memory faults. When the CPU traps an access violation, the operating system delivers a structured exception on Windows or a signal on POSIX, and if nothing handles it the process dies. A log line saying the game closed is useless. What you want is the call stack, the register values, the loaded module list, and the thread that faulted, all captured at the instant of the trap.

A minidump is exactly that snapshot in a compact, well documented format. It records thread contexts, the stack memory, module base addresses, and optionally heap regions. It is small enough to upload from a player machine and complete enough to reconstruct the crash in a debugger. The catch is that a minidump on its own is just addresses; without matching symbols it shows numbers, not function names. So the workflow has two halves: capture the dump in the field, and resolve it later against the symbols for that exact build.

Installing handlers: SEH and signals

On Windows you register an unhandled exception filter with SetUnhandledExceptionFilter. Inside it you call MiniDumpWriteDump from dbghelp, passing the EXCEPTION_POINTERS you received so the dump records the faulting context. Be careful: the handler runs in a corrupted process, so keep it minimal, avoid heap allocation, and pre open the dump file handle at startup. Vectored exception handlers and the newer __try and __except blocks around your main loop give you finer control, but the global filter is the backstop that catches everything you did not anticipate.

On Linux and other POSIX targets you install handlers for SIGSEGV, SIGABRT, SIGFPE, SIGILL, and SIGBUS with sigaction, and you run them on an alternate signal stack set up by sigaltstack so a stack overflow does not defeat the handler. From the handler you can walk the stack and write a minidump style record, or you can lean on a library. Google Breakpad and its successor Crashpad implement all of this correctly across platforms, including the out of process model where a separate handler process survives the crashing game and writes the dump reliably.

Symbols, PDBs, and symbol servers

A dump is only as good as the symbols you can match to it. On Windows that means the PDB file produced alongside each build, keyed by a unique GUID and age stamp embedded in the executable. If you ship a build, you must archive its PDBs. The clean way to do this is a symbol server: a directory or HTTP store laid out by symbol key, populated with symstore or a CI step, so a debugger can fetch the exact PDB for any dump automatically. Never overwrite symbols between builds; every shipped binary needs its own.

On Linux the equivalent is the debug info, either kept in the binary or split into separate .debug files indexed by build id. Breakpad converts both PDBs and ELF debug info into its own .sym text format with the dump_syms tool, which lets one symbol pipeline serve every platform. The discipline is the same everywhere: tie symbols to the build at the moment you produce it, store them by their key, and make sure your crash pipeline can look them up. Skip this and your dumps resolve to a wall of hexadecimal.

Turning a dump into a readable crash

Once a dump reaches you, resolution is mechanical. With WinDbg or Visual Studio you open the dump, point the debugger at your symbol server, and it walks the faulting thread into named frames with file and line. From the command line, cdb with the .ecxr and k commands does the same. With Breakpad, minidump_stackwalk takes the dump plus your .sym directory and prints a full symbolized stack as text, which is ideal for an automated backend that ingests dumps and stores readable traces.

The frame you care about is rarely the top one. The top is often inside a system library or an allocator; the real bug sits a few frames down in your code where a freed pointer was reused or an index ran past an array. Reading the surrounding frames, the register values, and the function arguments where available is what turns a dump into a fix. Automating symbolization so every incoming crash arrives already resolved removes the tedium and lets you spend your attention on the diagnosis.

Setting it up with Bugnet

Bugnet gives you a place to send those dumps and the surrounding context without building a backend yourself. The SDK or your handler uploads the minidump along with the build version, platform, GPU and driver strings, and any player attributes you set, so each crash arrives with the stack trace and the device context attached rather than as a bare file. The in game report button can also let a player add a note about what they were doing, which pairs the technical snapshot with a human description of the moment it happened.

Because native crashes cluster hard around a handful of bad pointers, occurrence grouping matters here more than almost anywhere. Bugnet folds duplicate dumps that resolve to the same faulting frame into one issue with a count, so a thousand reports of the same access violation become a single prioritized entry. You can filter by build, platform, or driver version to see whether a crash is universal or limited to one configuration, and custom fields let you tag the subsystem so the right person picks it up.

Make capture part of the build

Crash handling is not a feature you bolt on at the end; it is part of your release process. Every shipping configuration should install the handler at startup before any game code runs, and your continuous integration should publish the matching symbols to your store as an inseparable step of producing the binary. Test the path deliberately: trigger a fault in a debug session, confirm a dump is written, confirm it uploads, and confirm it symbolizes to the line you expect. A crash pipeline you have never exercised is one that fails the first time it matters.

Once the loop is reliable you stop fearing the silent close. A native game will always have memory bugs that only appear on hardware you do not own, and the difference between a stable launch and a painful one is whether those bugs arrive as readable, grouped, symbolized stacks or as vague reports that you cannot reproduce. Build the capture in early, keep your symbols forever, and let the field do your hardest debugging for you.

Capture the dump in the field, keep the symbols forever, and resolve offline. A native crash is only debuggable if you saved both halves.