App crashes on the Mac are generally pretty rare. But when they do happen, you might want to trace their cause. And if you’re a developer, you need to understand why your app is crashing. Here’s how to read macOS crash reports and sort through the cryptic language.
Also read: 8 Ways to Fix Unresponsive Apps and System Freezes on Mac
Opening Crash Reports
When an app crashes on your Mac, it automatically generates a crash report. You’ll see this appear after the crash with a warning dialog saying “[App] has quit unexpectedly.” That crash report is available to read immediately in that window by clicking the “Report …” button. The crash report can also be found in the Console app.
1. Open the Console application by typing “Console” into Spotlight or navigating to “Application -> Utilities -> Console.app.”
2. Click on “User Reports” in the left menu, then click on the crash report you want to view. All these files will end in “.crash” and include the date and crashed application in the title. The details of the crash report are available in the pane on the right.
Reading macOS Crash Reports
Let’s navigate the crash report from top to bottom.
What crashed?
The first part of the crash report tells you what “process” or application crashed. The most important part for the average troubleshooter is the process name.
Process: aText [11473] Path: /Applications/aText.app/Contents/MacOS/aText Identifier: com.trankynam.aText Version: 2.19 (62) Code Type: X86-64 (Native) Parent Process: ??? [1] Responsible: aText [11473] User ID: 501
When did it crash?
The second part tells us when the crash occurred. It also provides a little information about your system.
Date/Time: 2018-03-15 00:58:10.552 -0400 OS Version: Mac OS X 10.12.6 (16G1036) Report Version: 12 Anonymous UUID: 6C985CFD-6975-3F30-50EB-0713315F5090 Time Awake Since Boot: 630000 seconds System Integrity Protection: enabled
What caused the crash?
The next part is the most illuminating. The”exception type” provided by the application tells us what caused the crash. The log also reports which thread crashed: in this case, thread 0.
Crashed Thread: 0 Dispatch queue: com.apple.main-thread Exception Type: EXC_BAD_ACCESS (SIGSEGV) Exception Codes: KERN_INVALID_ADDRESS at 0x000040dedeadbec0 Exception Note: EXC_CORPSE_NOTIFY Termination Signal: Segmentation fault: 11 Termination Reason: Namespace SIGNAL, Code 0xb Terminating Process: exc handler [0]
Apple lists some common exception types in their technical documentation:
- Bad Memory Access (
EXC_BAD_ACCESS/SIGSEGV/SIGBUS) – the program attempts to access memory incorrectly or with an invalid address. Appended with a code explaining the memory issue. - Abnormal Exit (
EXC_CRASH/SIGABRT) – abnormal exit, typically at the hand of an uncaught C++ exception and calls toabort() - Trace Trap (
EXC_BREAKPOINT/SIGTRAP) – like SIGABRT, but this exit gives the attached debugger the chance to interrupt the process at a breakpoint and trace the error. - Illegal Instruction (
EXC_BAD_INSTRUCTION/SIGILL) – the processed issued an instruction that wasn’t understood or couldn’t be processed. - Quit (
SIGQUIT) – the process was terminated by another process with sufficient privileges. Typically, a watchdog process terminates a misbehaving process. - Killed (
SIGKILL) – the process was terminated at the request of the system. A termination code will be appended to explain the exception.
As we can see from our crash report, the application tried to access unmapped memory. This is due to a programming error in the application or an unusual user state causing the application to map memory incorrectly.
What lead to the crash?
After that we see a reverse chronological list of what lead up to the crash. These are sorted by thread, starting with thread 0.
There are four columns to this report. The first reports the event’s number in reverse chronological order, starting at 0. The second is the process’s identifier. The third is the address of the process in memory. The fourth is the name of the program’s task.
This “backtrace” can be somewhat baffling. It’s “symbolicated,” meaning some of the memory addresses have been replaced with function names or application tasks. Sometimes this can’t be done completely, leaving unreadable memory addresses scattered through the report.
We see this in the crash report above: com.trankynam.aText is not symbolicated. Even with complete symbolication, it can be hard to read the backtrace. Sometimes developers include useful notes about application tasks and events. Other times, they’re cryptic titles or numerical code. If you can make sense of the symbolication, you might be able to understand what’s happening. But it’s equally as possible that you’ll need to have coded the application yourself to make sense of the backtrace.
Conclusion: Is This Useful?
If you’re a developer, reading crash reports is essential. It helps you understand what part of your application is crashing and why. If you’re a user, they’re not as helpful. But if you have a persistent crash, the crash reports can help you troubleshoot the issue or work with the developer to fix the problem. You might get a useful error code to Google or be able to provide tech support with the right information. If you want the gory details, you can read all about it in Apple’s technical note on crashes.
Our latest tutorials delivered straight to your inbox
