How to Handle Platform-Specific Crash Reports

Shipping a game on multiple platforms means receiving crash reports in multiple formats, each with its own structure, symbolication requirements, and quirks. A Windows minidump is a binary blob that requires Microsoft’s debugging tools to read. A macOS crash log is a plain-text file with a specific header layout. An Android tombstone buries the useful information under pages of memory maps. An iOS crash report is JSON wrapped in a file extension nobody recognizes. If your team handles each format separately, you end up with fragmented data, duplicated effort, and crashes that slip through because nobody realized the same null pointer dereference was happening on three platforms at once.

Understanding the Four Major Formats

Windows crash reports come as minidump files (.mdmp). A minidump contains the state of every thread at the moment of the crash, the exception record, loaded module addresses, and optionally a slice of the stack memory. The file is binary and requires a debugger — WinDbg, Visual Studio, or a command-line tool like minidumper — to extract a readable stack trace. The key information you need is the exception code (such as EXCEPTION_ACCESS_VIOLATION), the faulting module and offset, and the thread stack traces.

macOS crash logs are plain-text files generated by the system’s ReportCrash daemon. They contain a header with the process name, version, and OS version, followed by the exception type (usually EXC_BAD_ACCESS or EXC_CRASH), and then a list of threads with their backtraces. Addresses in the backtrace are raw unless the crash log was generated on a machine with the corresponding dSYM file. Symbolication requires running atos or symbolicatecrash against the correct dSYM bundle.

Android tombstones are generated by the debuggerd daemon when a native crash occurs. They are text files containing the signal number and fault address, register dumps, a backtrace for the crashing thread, stack memory contents, and a full memory map of the process. The backtrace contains addresses relative to loaded shared libraries, which must be symbolicated using ndk-stack or addr2line with the unstripped .so files from your build.

iOS crash reports use the .ips extension and, since iOS 15, are formatted as JSON. They include the exception type, faulting thread index, and per-thread backtraces with image offsets. Symbolication requires the matching dSYM bundle, just like macOS, and Apple provides symbolicatecrash as part of Xcode’s toolchain.

Setting Up a Symbol Server

Every crash report is useless without debug symbols. A raw backtrace shows addresses like 0x00007ff6a3b41f2c, which tells you nothing. With symbols, that address becomes CombatSystem::ApplyDamage(Entity&, float) at combat.cpp:247. The challenge is that you need the exact symbols for the exact build that crashed. A symbol server solves this by storing symbols indexed by build identifier.

# Example: uploading symbols for each platform after a release build

# Windows: upload .pdb files indexed by build GUID
symstore add /r /f "build/win64/*.pdb" /s "\\symbols\bugnet" /t "MyGame" /v "1.2.3"

# macOS / iOS: upload .dSYM bundles indexed by UUID
dsymutil build/macos/MyGame -o "symbols/MyGame.dSYM"
upload-symbols --uuid "$(dwarfdump --uuid build/macos/MyGame.dSYM)" --path "symbols/"

# Android: upload unstripped .so files indexed by build ID
upload-symbols --build-id "$(readelf -n libs/arm64-v8a/libgame.so | grep 'Build ID')" \
  --path "libs/arm64-v8a/libgame.so"

Your CI pipeline should upload symbols automatically on every build that could reach players. This includes release builds, beta builds, and any internal QA builds that testers might crash on. If a crash report arrives and you do not have the matching symbols, that report is effectively lost — you will see addresses but never function names. Make symbol upload a blocking step in your release pipeline: if it fails, the build does not ship.

Normalizing Crash Data Across Platforms

Once you can symbolicate crash reports from every platform, the next step is parsing each format into a single unified structure. A normalized crash record should contain the platform and OS version, your game’s build version, the exception type mapped to a common vocabulary, the crashing thread’s symbolicated stack trace, device information (GPU, RAM, CPU architecture), and a crash fingerprint for grouping.

The fingerprint is critical. Two crashes are “the same crash” if they hit the same bug, even if one is on Windows and the other on Android. A good fingerprinting strategy takes the top three to five frames of the crashing thread that belong to your code — ignoring OS frames, runtime frames, and third-party library frames — and hashes them into a group key. This lets you see that CombatSystem::ApplyDamage is crashing on all four platforms and treat it as a single issue rather than four separate tickets.

// Pseudocode: generating a cross-platform crash fingerprint
func generateFingerprint(frames []StackFrame) string {
    relevant := []string{}
    for _, frame := range frames {
        if frame.Module == "MyGame" || frame.Module == "libgame.so" {
            relevant = append(relevant, frame.Function)
        }
        if len(relevant) >= 5 { break }
    }
    return sha256(join(relevant, "|"))
}

Handling Platform-Specific Edge Cases

Each platform has quirks that complicate crash processing. Windows minidumps can be captured with different levels of detail — a MiniDumpNormal contains only thread stacks, while a MiniDumpWithFullMemory can be hundreds of megabytes. For a game with millions of players, you want the smallest useful dump. Configure your crash handler to capture MiniDumpWithIndirectlyReferencedMemory, which includes the stack and any heap objects referenced by stack pointers, typically producing files under five megabytes.

On Android, crashes in Java code produce a different format than native crashes. If your game uses a mixed Java/native architecture — common with engines like Unity on Android — you need to handle both JVM stack traces and tombstone-style native traces. The JVM trace will often show a SIGABRT that originated from a native call, so you need to stitch the Java and native stacks together to get the full picture.

On iOS, Apple’s privacy protections mean that crash reports from the App Store are delivered through App Store Connect with a delay of up to 24 hours. If you want real-time crash data, you need to install your own crash handler using a library like PLCrashReporter that captures and uploads reports immediately. Be aware that Apple’s MetricKit can conflict with custom crash handlers if both attempt to catch the same signal.

“We shipped on four platforms with separate crash trackers for each. When a critical crash spiked after a patch, it took us two days to realize it was the same root cause everywhere. After unifying our crash pipeline, cross-platform issues now show up as a single entry with platform tags. That two-day delay disappeared.”

Building the Ingestion Pipeline

Your crash ingestion pipeline should accept uploads from all platforms through a single HTTP endpoint. The client-side crash handler captures the platform-native report, attaches metadata (build version, OS version, device model, a session identifier), and uploads it. The server identifies the format by the content type or a platform header, routes it to the correct parser, symbolicates it against the symbol server, normalizes it into your unified schema, generates a fingerprint, and either groups it with an existing crash issue or creates a new one.

Rate limiting on the ingestion endpoint is important. A crash loop — where the game crashes on startup, the player relaunches, and it crashes again — can generate thousands of duplicate reports from a single player. Deduplicate by session ID and throttle uploads to a maximum of five reports per session. On the server side, once a crash group exceeds a configurable sample threshold (such as one hundred reports), stop storing full crash payloads and only increment the counter. You already have enough data to diagnose the issue; additional reports add storage cost without diagnostic value.

Related Resources

For a comprehensive overview of crash reporting tools, see automated crash reporting for indie games. To set up crash reporting in your engine, read add crash reporting in Unity or Godot in 10 minutes. For strategies on prioritizing which crashes to fix first, check out bug reporting metrics every game studio should track.

Add symbol upload to your CI pipeline today. The next crash report that arrives with full function names and line numbers will save you hours of guesswork.