Missing dSYM? Make iOS crash reports show real function names
Short answer: If your iOS app's crash reports show memory addresses instead of function names, or your crash tool warns about a "missing dSYM", the debug symbol file for that build never reached it. Set the release build to produce a dSYM, keep the Xcode archive for every version you ship, upload the dSYM for each build (automatically from the build pipeline if possible), and recover old ones by their build UUID. Crash reports are only useful when each build's matching dSYM is in place.
What a dSYM is and why it goes missing
When Xcode builds your app for release, the code your developers wrote is compiled into a binary that doesn't carry readable function names. The names live in a separate debug symbol file, the dSYM. Crash tools use it to turn a list of addresses from a user's phone into a readable stack trace that points to the file and function where the crash happened.
Apple's documentation stresses one detail that explains most problems: a binary and its dSYM are tied together by a build UUID recorded in both. If you build the same source code twice with different Xcode versions or build settings, the UUIDs won't match, and a dSYM is only compatible with a binary that has an identical build UUID. A "close enough" dSYM from yesterday's build won't work.
The usual causes of missing dSYMs:
- The release configuration doesn't produce dSYM files at all.
- The upload step was never added to the machine that actually built the release, such as a new CI service.
- The build's archive was deleted, so the matching file is gone.
- A hotfix was built and shipped in a hurry by hand, skipping the usual pipeline.
Step 1: Make sure Xcode produces dSYMs
Firebase Crashlytics' troubleshooting guide says that, more often than not, dSYM files go missing because Xcode isn't producing them. Apple's documentation describes the setting: the Debug Information Format build setting should be "DWARF with dSYM File" for the builds you distribute.
Ask your developer to check:
- In the target's Build Settings, the Debug Information Format for Release (and any other shipped configuration) is "DWARF with dSYM File".
- Each framework or extension target you ship follows the same rule, since they produce their own dSYMs.
- After the next archive, a dSYMs folder exists inside the
.xcarchivepackage.
Step 2: Keep every archive
Apple's documentation includes an important note: you must retain the Xcode archive for each build you distribute, because without it you might not be able to diagnose issues from crash reports. The dSYMs sit inside the archive.
In practice:
- If you build in Xcode, don't delete old archives in the Organizer for versions still in use.
- If you build on CI, save the
.xcarchiveor at least its dSYMs folder as a build artefact, labelled with the version and build number. - Keep them for as long as anyone runs that version.
Step 3: Get dSYMs to your crash tool
App Store Connect. Apple's documentation explains that when you upload to App Store Connect for the App Store or TestFlight, you can include symbol files so Apple can add symbol names to the crash reports it delivers to you in Xcode.
Third-party crash tools. Tools like Crashlytics, Sentry or Bugsnag need their own copy. Crashlytics normally uploads dSYMs through a run script in the Xcode build phases. Its guide lists the input file paths the script needs, and notes that recent Xcode setups using debug dylibs need an extra path. If the script runs only on a developer's laptop and not on CI, CI builds will be missing symbols.
Step 4: Recover a missing dSYM
When the console shows a "Missing dSYM" alert with a UUID, the Crashlytics guide describes how to find it:
- Search your Mac for dSYMs and print their UUIDs with
mdfind -name .dSYManddwarfdump -u, then match the UUID from the alert. - Look in the Products directory in Derived Data, or open the Organizer, show the archive in Finder, use Show Package Contents and open the dSYMs folder.
- Upload the matching file through the crash tool's console or its
upload-symbolsscript.
If no file with that UUID exists anywhere, rebuilding won't help, because a new build produces a new UUID. Reports for that build stay unreadable; fix the process so the next build is covered.
Step 5: Make it boring and automatic
A routine that holds up under pressure:
- The release pipeline archives, uploads to App Store Connect with symbols, and uploads dSYMs to your crash tool in the same job.
- The job fails if no dSYM is produced or the upload step reports an error.
- Archives are stored with the release record.
- After each release, someone checks one report, or triggers a test crash on an internal build, to confirm names appear.
- "Missing dSYM" alerts go to the person who owns releases, treated as a release bug.
An illustrative example
A hypothetical Leeds pet-supplies app moved its builds from a developer's laptop to a hosted CI service. Two releases later, every crash report showed addresses, and the console listed missing dSYMs. The upload run script existed only in the laptop's local Xcode setup. Because the CI service kept archives as artefacts, the team found both dSYMs by UUID, uploaded them, and the reports became readable. They then added the upload to the CI job and a check that fails the build when no dSYMs folder is produced.
FAQ
Can old crash reports become readable after uploading a dSYM?
Often yes, once the matching file is uploaded; the Crashlytics guide describes manual upload for this case. Behaviour differs by tool, so check yours.
Can I just rebuild the old version to get its dSYM?
Usually not. A new build gets a new UUID, and Apple's documentation says a dSYM only matches a binary with an identical build UUID.
Do I need dSYMs for TestFlight builds?
Yes, if you want readable crash reports from testers.
Is this a developer task or a business one?
Both. Developers set it up; whoever owns releases makes sure it never gets skipped.
If your iOS crash reports are unreadable and you'd like the build and release steps checked, tell us how your app is built and shipped.