---
title: "Debugging iOS crash reports with LLDB and Xcode"
slug: "debug-ios-crash-report"
blurb: "How to use LLDB and Xcode to interactively step through a crash report"
cover:
  url: "/assets/posts/debug-ios-crash-report/feature-debug-ios-crash-report-desktop@1x.webp"
  alt: "How to use LLDB and Xcode to interactively step through a crash report"
socialThumbnail:
  url: "/assets/posts/debug-ios-crash-report/feature-debug-ios-crash-report-desktop@1x.webp"
  alt: "How to use LLDB and Xcode to interactively step through a crash report"
author:
  - "delisa"
tags:
  - "engineering"
publishedDate: "2026-11-16T13:26:41.146Z"
modifiedDate: "2026-11-16T13:26:41.146Z"

---

The `ScriptedProcess` API and `crashlog` module in [LLDB](https://lldb.llvm.org/) make it possible to examine crash reports interactively in a debugger, almost as if encountering an issue live. You can use this workflow to examine crash reports from the comfort of your favorite debugging environment and with the added context of the surrounding source code, hopefully revealing potential fixes.

## Getting started

### Step 1: Get a crash report

To get started debugging your iOS issues tracked by bitdrift Capture, click "Debug with Xcode" from the issue details view, which will download the issue as an Apple crash report:

<Image alt="Highlighting the Debug with Xcode button on a bitdrift Issue Detail page" altAsCaption large asset="/assets/posts/debug-ios-crash-report/debug-with-xcode-button@1x.webp" />

The following steps also work with any other crash report obtained from your Apple devices, such as the ones available in the Xcode Organizer.

### Step 2: Open the crash report in Xcode or LLDB

Context-click the file and open with Xcode, selecting the corresponding Xcode project:

<Image alt="A synthetic debugging session in Xcode" altAsCaption large asset="/assets/posts/debug-ios-crash-report/xcode-synthetic-debugging-session@1x.webp" />

or open directly with LLDB using `xcrun crashlog --interactive path/to/file`, optionally specifying the app binary using `--target`:

<Image alt="A synthetic debugging session in LLDB" altAsCaption large asset="/assets/posts/debug-ios-crash-report/lldb-synthetic-debugging-session@1x.webp" />

### Step 3: Start debugging

The debugger is now active to accept regular debugging commands, like `thread info` to see the current thread state, `register read` for  register data when available, `disassemble` to view instructions as particular memory locations, or `frame select [index]` to step through the backtrace.

## How it works

LLDB is designed as a collection of modular components, and for most cases, the process context (like memory region info, thread data, and breakpoints) underpinning a debugging session is provided by the debug server process implementation, which drives a live process, responds to commands, and exposes the process for introspection.

The [`ScriptedProcess`](https://lldb.llvm.org/python_api/lldb.plugins.scripted_process.ScriptedProcess.html) API provides similar capabilities by exposing hooks to define process and thread information from an alternative source, simulating a running process. For example, implementing `get_process_id()` provides the process ID shown when using `process status` in LLDB, and the thread and stack frame data comes from `get_threads_info()` and implementing [`ScriptedThread`](https://lldb.llvm.org/python_api/lldb.plugins.scripted_process.ScriptedThread.html#lldb.plugins.scripted_process.ScriptedThread). By implementing this API, it is possible to provide a debugging environment across platforms or from unconventional sources.

```python
# A selection from the ScriptedProcess interface
class ScriptedProcess:
	def get_process_id(self) -> int: ...
	def get_threads_info(self) -> dict[int, ScriptedThread]: ...
	def read_memory_at_address(self) -> SBData: ...
	...

class ScriptedThread:
	def get_name(self) -> str: ...
	def get_register_info(self) -> dict[str, Any]: ...
	def get_stackframes(self) -> list[ScriptedFrame]: ...
	...
```

The `crashlog` module, which is bundled with an installation of Xcode, implements `ScriptedProcess` for the standard and JSON formats of Apple crash reports, additionally performing symbolication of stack frames to provide function and file information to the session. Xcode automatically launches LLDB and `crashlog` when opening a crash report, starting a debugging session.

## Learn more

Check out the WWDC session [Run, Break, Inspect: Explore effective debugging in LLDB](https://developer.apple.com/videos/play/wwdc2024/10198/) for more on debugging with LLDB and for other great tips for making the most of crash reports. There is also a guide to [Examining the fields in a crash report](https://developer.apple.com/documentation/xcode/examining-the-fields-in-a-crash-report) in the Apple developer documentation.

See the LLVM Dev meeting talk by Med Ismail Bennani titled ["Interactive Crashlogs"](https://www.youtube.com/watch?v=iM2EH5EmoSY) for more on the `crashlog` module, which also has [source code available in the LLVM repository on GitHub](https://github.com/llvm/llvm-project/blob/main/lldb/examples/python/crashlog.py).

For more on LLDB plugins and implementing `ScriptedProcess`, see the documentation for the [LLDB Python extensions](https://lldb.llvm.org/python_extensions.html), such as the [guide to creating custom commands](https://lldb.llvm.org/use/tutorials/writing-custom-commands.html) and the [`ScriptedProcess` interface](https://lldb.llvm.org/python_api/lldb.plugins.scripted_process.ScriptedProcess.html).

---

## Add the context a crash report can’t give you with bitdrift

A crash report shows you the state of the app at the moment it crashed, but not how it got there. When you open a crash from bitdrift Capture, you also have the full session timeline for that user: the logs, network requests, and app events leading up to the crash, captured on-device and available without sampling. Use the debugger to see where the app failed, and the session timeline to understand why.

Get started with the [bitdrift sandbox](https://bitdrift.io/sandbox).

## Common questions

### Do I need dSYMs to debug an iOS crash report in LLDB?

To see function names and source file information, LLDB needs the matching debug symbols (dSYMs) and app binary for the build that crashed. Without them, the crashlog module can still load the report, but stack frames will show memory addresses instead of function names for release app builds.

### Does this only work with crash reports from bitdrift?

Nope! LLDB’s crashlog module works with any Apple crash report in the standard text or JSON format, whether it comes from bitdrift Capture, Xcode Organizer, App Store Connect, or a user who shared it from their device. bitdrift Capture makes it a one-click download from the issue details view.
