App crashes on the Mac are generally pretty rare. But when they do happen, you might want to trace back their cause. You can troubleshoot app crashes by looking at macOS crash reports. But you need to know how to read crash reports on macOS to decode the cryptic language of the reports. Learn how to read crash reports on macOS here.
Opening Crash Reports on macOS
Whenever an app crashes in macOS, it automatically generates a crash report. It also pops up a dialog box informing the user that “[App Name] quit unexpectedly.” From this dialog box, you’ll have the option to reopen the application, ignore the crash, or click the “Report…” button. The last will reveal the crash report immediately, allowing savvy users to troubleshoot the app’s recent demise. You also have the option of sending a copy of the report to Apple, so they can collect data about what’s causing applications to crash.
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. Select a crash report from the middle pane. Note the time and app names in each report’s title. Once you select a report, view the details in the right-hand pane.
How to Read Crash Reports on macOS
Crash reports should be read from top to bottom. We’ll take it from the top.
The first several lines of the crash report tell the user what “process” (AKA application) crashed. This process name will also be in the title of the crash report. We can see the text of our own crash report reproduced below for examination. Note the process name and identifier, which will come up later.
Process: aText  Path: /Applications/aText.app/Contents/MacOS/aText Identifier: com.trankynam.aText Version: 2.19 (62) Code Type: X86-64 (Native) Parent Process: ???  Responsible: aText  User ID: 501
When did the process crash?
Once we know what crashed, we will want to know when it crashed. That information is included in the second part, along with a little info about our 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 third part of the report gives us the most important detail: why the crash happened. When applications quit without warning, they send up a flag indicating why they’re quiting. There’s a number of reasons (the popular ones are below) and they can help explain why the application crashed. macOS crash reports call this flag the “exception type,” and we can find it in this section. We will also learn which thread crashed, typically thread 0. That might help us pinpoint the cause of the crash too.
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 
The information prefixed with “Termination” provides more detail about what quit the application and how. In this case, we learn than a segmentation fault caused the application to crash, and the process “exc handler” was in charge of closing out the misbehaving application. Apple lists some common exception types in their technical documentation. You’ll find this listed in your own crash reports under “Exception Type”:
- Bad Memory Access (
SIGBUS) – the app didn’t access memory properly. Will be followed by an “exception code” expanding on what kind of memory error occured.
- Abnormal Exit (
SIGABRT) – abnormal exit. This is usually due to an uncaught C++ exception or a call to the function
- Trace Trap (
SIGTRAP) – like
SIGABRT, but this exit gives the attached debugger the chance to trace the error.
- Illegal Instruction (
SIGILL) – the process issued an instruction that wasn’t understood or couldn’t be processed.
As we can see from our crash report, the application most likely to access memory it didn’t “own” and crashed as a result. It looks like the application expected to be able to send data somewhere, but found out that the destination was no longer valid when trying to communicate. This could be due to an unusual user state causing the application to map memory incorrectly, or even a bug in the software. Provided the crash doesn’t happen again, we can likely safely ignore it.
What lead to the crash?
After all that information, we’ll see the “backtrace.” This is a list of all the running functions and tasks, in reverse chronological order, leading up to the crash.
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 part of the crash report isn’t that useful to a typical user. But for a developer, it’s essentially. Regardless of its utility, the backtrace can be baffling. It’s “symbolicated”: at least some memory addresses are replaced with function names. Sometimes symbolication can be completed, leaving untranslated memory addresses sprinkled throughout the backtrace. Even with complete symbolication, it can be hard to know how to read crash reports in macOS. It depends largely on how thorough developers name and describe their functions, and on how well you can put together the pieces of this puzzle. The more you know about programming for macOS, the better you’ll be at interpreting a backtrace.
Conclusion: Is This Useful?
Knowing how to read crash reports on macOS is an essential skill for developers. It will help devs figure out what’s crashing and why. Users, however, might not get as much value from the reports. Crash reports can offer some troubleshooting information for persistent crashes, but you need a thorough understanding of the OS and the application to make good use of the data. Nevertheless, persistent users might get a useful error code to Google, or be able to provide tech support with the right information to solve the problem. If you want to dig into the technical information about crash reports, check out Apple’s technical note on crashes and crash reports.
You might also like the following posts: