Skip to content

How to Capture & Report macOS Crashes

Jump to bottom
Felipe Braz edited this page Aug 25, 2026 · 1 revision

When Command & Conquer: Generals or Zero Hour (GeneralsX) unexpectedly quits or crashes (often due to a segmentation fault / SIGSEGV / EXC_BAD_ACCESS), macOS captures a detailed crash report containing critical diagnostic information.

This guide explains how macOS Crash Reporter works, how to retrieve the crash report, why this debug information is vital for the development team, and how to capture live backtraces with lldb if needed.

1. The macOS Crash Dialog ("Quit Unexpectedly")

When GeneralsX crashes, macOS displays a system dialog stating:

"GeneralsXZH quit unexpectedly."
Click Reopen to open the application again. Click Report to see more detailed information and send a report to Apple.

┌─────────────────────────────────────────────────────────────┐
│ ⚠️  GeneralsXZH quit unexpectedly.                          │
│                                                             │
│ Click Reopen to open the application again.                 │
│ Click Report to see more detailed information and send a    │
│ report to Apple.                                            │
│                                                             │
│  [ Ignore ]            [ Report... ]             [ Reopen ] │
└─────────────────────────────────────────────────────────────┘

How to Extract the Crash Report

  1. Click the Report... button (or Show Details depending on your macOS version).
  2. A new window will open with a large text box containing the technical crash log.
  3. Select all the text (Cmd + A) and copy it (Cmd + C), or expand the details and copy the top section including:
    • Header (Process, Identifier, Code Type, OS Version, Exception Type, Exception Codes)
    • Crashed Thread (e.g., Thread 0 Crashed:: Dispatch queue: com.apple.main-thread)
    • Stack Trace of the Crashed Thread (Frames 0, 1, 2, ... listing function symbols and offsets)
  4. Paste this text into your GitHub issue report.

2. Finding Past Crash Logs (.ips / .crash)

If you accidentally closed the crash dialog or clicked "Ignore", macOS saves the report to your system disk.

Option A: Using the macOS Console App (Easiest)

  1. Open Console.app (Press Cmd + Space, type Console, and hit Enter).
  2. In the left sidebar, click on Crash Reports (or User Reports on older macOS versions).
  3. Look for files starting with GeneralsX or GeneralsXZH (e.g., GeneralsXZH-2026-08-25-173000.ips).
  4. Click on the file to view the report, right-click to copy, or reveal it in Finder.

Option B: Accessing Files Directly via Finder or Terminal

Crash files are stored in the user's diagnostic directory:

  • Path: ~/Library/Logs/DiagnosticReports/

You can open this folder directly in Finder:

open ~/Library/Logs/DiagnosticReports/

Look for recent .ips or .crash files matching GeneralsX*.

3. macOS Crash Reporter Configuration (Optional)

If macOS is not displaying the dialog after a crash, the crash reporter might be operating in non-interactive server mode. You can ensure the dialog appears or set it to developer mode using Terminal:

# Enable standard crash report dialog
defaults write com.apple.CrashReporter DialogType crashreport

# (Alternative) Enable developer mode (shows full details immediately)
defaults write com.apple.CrashReporter DialogType developer

To revert to the default behavior:

defaults delete com.apple.CrashReporter DialogType

4. Why This Debug Information Is Essential

GeneralsX is a modernized codebase consisting of over 500,000 lines of C++ code interacting with:

  • Game Engine Logic: State machines, units, scripting, and pathfinding.
  • Vulkan / DXVK Translation: DirectX 8 translated to Vulkan via MoltenVK.
  • Audio Subsystems: OpenAL / MiniAudio threads.
  • SDL3 Layer: Windowing, display, and input events.

When a crash occurs, a simple description like "the game closed during mission 2" does not provide enough clues to identify the fault.

The macOS crash report reveals:

  1. The Culprit Subsystem: Shows whether the crash happened in game logic, DXVK, graphics driver (libMoltenVK.dylib / Metal), or audio (OpenAL).
  2. The Exact Function Call: Points directly to the C++ method (e.g., GameLogic::update(), Drawable::draw(), or AudioDevice::process()).
  3. The Root Cause: Indicates null pointer dereferences, heap corruptions, out-of-bounds array access, or invalid memory accesses (EXC_BAD_ACCESS / KERN_INVALID_ADDRESS).

5. Advanced: Capturing a Live Backtrace with LLDB

If you can reliably reproduce a crash and are running from the terminal or source build, running under LLDB (the macOS debugger) provides the highest level of debugging fidelity:

  1. Open Terminal and navigate to the build output directory containing the executable:

    cd ~/GeneralsX/build/macos-vulkan/GeneralsMD

  2. Launch the game inside LLDB:

    lldb ./GeneralsXZH

  3. Start execution:

    (lldb) run -win

  4. Play until the game crashes. LLDB will catch the signal and pause execution.

  5. Print the call stack of the crashed thread:

    (lldb) bt

  6. Or print call stacks for all active threads:

    (lldb) thread backtrace all

  7. Copy the output and attach it to your bug report.

6. How to Submit a Bug Report

When opening an issue for a macOS crash on GitHub:

  1. Title: Include platform and brief symptom (e.g., [macOS] Crash on game start in Vulkan pipeline or [macOS] Segfault when selecting China Nuke Cannon).
  2. Environment: Mention your Mac model (M1/M2/M3 Apple Silicon or Intel) and macOS version (e.g., macOS 14 Sonoma / macOS 15 Sequoia).
  3. Steps to Reproduce: Exact steps, map played, faction chosen, or mod used.
  4. Crash Log: Paste the crash report inside a collapsible block or code fence: 
    <details>
<summary>macOS Crash Report</summary>

```text
PASTE_CRASH_REPORT_HERE
```
</details>
  5. Console / Engine Logs: If available, attach logs/build_zh_macos.log or console output.

Clone this wiki locally