How to Read macOS Crash Reports to Troubleshoot Your Mac

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.

how-to-read-crash-reports-1

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.”

how-to-read-crash-reports-2

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.

console-read-crash-reports-2

Let’s navigate the crash report from top to bottom.

What crashed?

console-read-crash-reports-3

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.

When did it crash?

console-read-crash-reports-4

The second part tells us when the crash occurred. It also provides a little information about your system.

What caused the crash?

console-read-crash-reports-5

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.

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 to abort()
  • 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?

console-read-crash-reports-6

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.

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.

Leave a Reply

Yeah! You've decided to leave a comment. That's fantastic! Check out our comment policy here. Let's have a personal and meaningful conversation.