.crash report or a report Xcode cannot symbolicate, use the matching archive’s dSYM with atos, checking the image UUID, architecture, and load address first.Why this happens
A crash report records the memory addresses of code executing when an app stopped. Symbolication converts those addresses into readable function names and, when the necessary debug information is available, source locations. Without matching symbols, a stack frame may show an app name and an address instead of a useful function name.
The debug symbols must match the exact binary that produced the report. A dSYM from another build of the same app version may have a different UUID and cannot reliably symbolicate that binary. Manual symbolication also depends on selecting the right architecture, binary image, and load address.
Xcode’s crash-log interface has changed over time. Older Xcode releases allowed .crash files to be dragged into the device-log list. Current reports may also use the .ips format, so the extension alone is not a reason to rename a report.
How to fix it
1. Open the report in Xcode’s device logs
If the crash happened on a device you can connect, start with Xcode’s log viewer:
- Connect the iPhone or iPad to your Mac.
- In Xcode, choose Window > Devices and Simulators.
- Select the device and open View Device Logs.
- Find the crash by app name and time, then open it.
Give Xcode access to the archive and debug symbols for the build that crashed. If the report is symbolicated, its stack frames should contain readable names where matching symbols are available.
For an older Xcode installation, the equivalent route was Window > Devices, followed by View Device Logs > All Logs. That interface supported dragging a .crash file into the list. If you are working with that older interface, try importing a copy of the report there. Import behavior can differ in newer Xcode versions; use the manual method below if dragging the file is not available or does not produce useful symbols.
Do not delete existing logs just to make an imported report easier to find. Check the app and crash time instead, and keep a copy of the report before making changes.
2. Find the archive for the exact build
Locate the .xcarchive made from the build that crashed. In Xcode, open Window > Organizer, select the archive, and use Show in Finder. In Finder, Control-click the archive and choose Show Package Contents.
For an app named Foo, the relevant files are typically inside the archive at paths like these:
Foo.xcarchive/
Products/Applications/Foo.app/
dSYMs/Foo.app.dSYM/
The app executable is inside Foo.app. The executable name is not necessarily the same as the display name shown on the device. The dSYM contains a corresponding DWARF file, typically at:
Foo.app.dSYM/Contents/Resources/DWARF/Foo
You can work with copies of the app, dSYM, and crash report in a separate folder. Keep the originals and the archive intact. If the crashing frame belongs to one of your frameworks rather than the app executable, find that framework’s matching binary and dSYM instead.
3. Check the binary and dSYM UUIDs
Before resolving addresses, verify that the binary and dSYM belong together. In Terminal, run the following commands with paths adjusted to your files:
xcrun dwarfdump --uuid "Foo.app/Foo"
xcrun dwarfdump --uuid "Foo.app.dSYM"
Compare the UUID for the architecture in the crash report. The app binary and dSYM should have the same UUID for that architecture. Also compare it with the UUID for the app image in the report’s binary-image information.
If the UUIDs do not match, find the archive or dSYM for the build that actually crashed. Matching the app’s marketing version is not enough: two builds with the same version can contain different binaries.
This check matters because atos can return a result for an address even when the inputs are wrong. A plausible-looking function name is not proof that you used the correct symbols.
4. Symbolicate an address with atos
For a text .crash report, find the frame you want to investigate and the corresponding entry in Binary Images. You need:
- The frame’s instruction address.
- The load address of the image that owns that frame.
- The architecture used by that image.
- The matching dSYM’s DWARF file.
For example, suppose an arm64 app image loaded at 0x100000000 and the frame address is 0x100012344. From the folder containing the dSYM, run:
xcrun atos \
-o "Foo.app.dSYM/Contents/Resources/DWARF/Foo" \
-arch arm64 \
-l 0x100000000 \
0x100012344
Replace every example value with the value from your report. The -l argument is the image’s load address, not the address of the stack frame. Use the load address and symbols for the image named on that frame; an app’s load address does not apply to a framework frame.
Repeat the command for other addresses you need to inspect. Start with frames on the crashed thread, especially those belonging to your app or its own frameworks. If the output is still an address or an unexpected name, recheck the UUID, architecture, image, and load address before drawing conclusions.
A legacy .crash report often presents the image information in a Binary Images section. A modern .ips report may present the same kinds of information in a different structure. Use the report’s actual values rather than assuming that an example layout applies to both formats.
5. Handle missing or incomplete symbols
If you cannot find a matching dSYM, check the archive and any build artifacts saved for the release. A dSYM from a later rebuild is not a substitute unless its UUID matches the crashed image.
Even with the correct dSYM, not every frame is guaranteed to show a source line. The detail available depends on the symbols and debug information in that build. System-library frames are also separate from your app’s frames and require the appropriate system symbols.
Keep the original report while investigating. Crash reports can contain device and app details, so share them only with people who need them to diagnose the problem.
How to prevent it
- Keep the
.xcarchiveand its dSYMs for every build you distribute. - Record which build was sent to testers or released, so you can locate its archive later.
- Check UUIDs when a report stays unsymbolicated or a resolved name looks wrong.
- Preserve crash reports in their original format; do not rename
.ipsfiles to.crashas a substitute for conversion. - Use each frame’s own binary image, architecture, and load address when running
atos.
FAQ
Can I symbolicate a crash without the exact dSYM?
You may see some symbol names from the binary itself, but detailed symbolication requires matching debug information. A dSYM from a different build should not be assumed to match, even if the app version is the same.
Should I rename an .ips file to .crash?
No. Renaming changes the filename, not the report’s contents or format. Keep the original file and use a tool or Xcode interface that can read it.
Why does atos show a function that does not make sense?
The dSYM may belong to a different build, or the command may use the wrong architecture, image, load address, or frame address. Compare UUIDs first, then verify each value against the report.
Parts of this guide are adapted from content licensed under CC BY-SA 3.0; this article is shared under the same license.