All about Missing dSYMs

Fabric includes a tool to automatically upload your project’s dSYM. The tool is executed through the /run script, which is added to your Run Script Build Phase during the onboarding process. There can be certain situations however, when dSYM uploads fail because of unique project configurations or if you’re using Bitcode in your app. When an upload fails, Crashlytics isn’t able to symbolicate and display crashes, and a “Missing dSYM” alert will appear on your Fabric dashboard.

../_images/missing-dsyms-alert.png

Missing dSYMs can be manually uploaded following the steps outlined below.

Note

As an alternative to the automated dSYM upload tool, Fabric provides a command-line tool (upload-symbols)) that can be manually configured to run as part of your project’s build process. See the upload-symbols section below for configuration instructions.

Finding Your Missing dSYMs

The first step is to find your missing dSYM. If you’re missing a dSYM for a build that’s been released to the iTunes store and has Bitcode enabled, view the Bitcode instructions below.

Finding local dSYMs

To help find a dSYM on your local machine, run this command in an open terminal:

mdfind "com_apple_xcode_dsym_uuids == <UUID>"

Once you’ve found the local dSYM, follow the instructions below to upload it to Crashlytics.

If the mdfind command doesn’t return any results, you can manually look in different locations depending on how your project is being built.

Scheme Based Builds

If you build your project using the Xcode GUI, or invoke xcodebuild with the -scheme flag, then your build output directory is determined by the settings in Xcode’s “Locations” preferences:

../_images/scheme-1-xcode-locations-settings.png

You can click on the small circled arrow to go directly to your Derived Data directory in Finder. You can also click on the “Advanced…” button to determine where exactly the Derived Data directory is located:

../_images/scheme-1-xcode-derived-data.png

In this case, the Derived Data directory is located relative to the xcodeproj or xcworkspace.

Wherever your Derived Data directory is located, build products and dSYMs (if your target is configured to generate them) are placed into the Products directory, in a folder corresponding to the build configuration and platform selected at build time.

Target Based Builds

When invoking xcodebuild with the -target flag, the build product location is determined by the value in the build target setting CONFIGURATION_BUILD_DIR:

../_images/scheme-2-target-configuration-build-dir-setting.png

xcarchives

When archiving your project, dSYMs are placed inside of an xcarchive directory on disk. Open Xcode’s Organizer window (Window -> Organizer), find your app in the list on the left, and a list of archives generated for that project on the current computer is displayed. You can Control-click an archive to go to it in Finder:

../_images/xcarchives-1-xcode-organizer-archive-list.png

Once in Finder, Control-click on the xcarchive to see its contents:

../_images/xcarchives-2-show-contents-xcarchive.png

The xcarchive contains a directory called “dSYMs” that will contain any dSYMs generated as part of the Archive process. This is also the location that recompiled bitcode dSYMs are downloaded into when using the “Download dSYMs…” tool in the Xcode Organizer:

../_images/xcarchives-3-dsym-directory-xcarchive.png

Carthage

Each dependency pulled in using Carthage is a full git repository in your Xcode project’s directory structure. When Carthage builds these dependencies, it places build products into the Carthage/Build directory, with one directory per platform inside. dSYMs are found in each platform’s directory (Carthage/Build).

Downloading Bitcode dSYMs

For Bitcode enabled builds that have been released to the iTunes store or submitted to TestFlight, Apple generates new dSYMs. You’ll need to download the regenerated dSYMs from Xcode and then upload them to Crashlytics so that we can symbolicate crashes.

dSYMs for Bitcode enabled apps can be downloaded from Xcode’s Organizer. Select the specific Archive of your app and then hit the “Download dSYMs…” button which will insert the Bitcode compiled dSYMs into the original Archive. Then, manually upload the dSYM to Crashlytics via the “Uploading Missing Bitcode dSYM” instructions.

../_images/xcode-download-dsyms.png

If you’re unable to download your dSYM from Xcode’s Organizer, visit iTunes Connect, select “My Apps” and “Activity”. Then select the build you want to download the dSYMs for and click on “Download dSYM”.

../_images/download-dsym.png

Uploading Missing dSYMs

Once you’ve found your missing dSYM you can manually upload it by clicking on the “Missing dSYM” Alert’s View button or by going to your settings page, selecting your app, and clicking on the “Missing DSYMs” tab.

Required vs Optional dSYMs

On the “Missing DSYMS” tab, dSYMS are marked as “Required” or “Optional”.

Required dSYMs

All .app dSYMs are marked as required. When Crashlytics fails to receive one of these dSYMs we are unable to properly symbolicate crashes. Once a required dSYM is uploaded, Crashlytics will reprocess all impacted crashes for the last 7 days and you will see new issues appears in the crash dashboard.

Optional dSYMs

Optional dSYMs are usually .framework dSYMs which we did not receive. When we do not have an Optional dSYM, crashes are still processed and appear in your dashboard, but some frames are not symbolicated. Uploading an Optional dSYM will not result in reprocessing of crashes, but new crashes moving forward will have missing frames symbolicated.

If a build is missing both an Optional and Required dSYM, Optional dSYMs should be uploaded first, followed by the Required dSYMs. This will ensure that Crashlytics can properly symbolicate all frames when the Required dSYMs are uploaded.

Uploading On-Disk dSYMs

On the “Missing dSYMs” page, upload a .zip folder containing multiple dSYMs or, zip and upload a single dSYM.

Uploading Bitcode dSYMs

On the “Missing dSYMs” page, upload the .zip of dSYMs that you downloaded from Xcode or iTunes Connect.

Note

The system requires a short amount of time (typically a few minutes) to process your uploaded dSYM. If the dSYM is listed as “missing” after the upload, reload the page after a few minutes have passed. If the dSYM continues to appear as missing, double check that your dSYM contained the missing UUID by running dwarfdump -u <PathToYourAppsDsym>.

Upload Symbols Script

Fabric includes an upload-symbols script that you can call anywhere in your build process to upload your dSYMs.

It’s included in the Fabric OS X app at Fabric.app/Contents/MacOS/upload-symbols and in the Fabric CocoaPod payload at $PODS_ROOT/Fabric/upload-symbols

You can use the following command to upload all dSYMs in a folder during your build process:

find <directory-to-search-for-dsyms> -name "*.dSYM" | xargs -I \{\} /path/to/upload-symbols -a <api-key> -p <platform> \{\}

If you run upload-symbols without any parameters, you’ll get usage notes that will provide additional instructions.