iOS Symbolication

Important

Visual Studio App Center is scheduled for retirement on March 31, 2025. While you can continue to use Visual Studio App Center until it is fully retired, there are several recommended alternatives that you may consider migrating to.

Learn more about support timelines and alternatives.

macOS, tvOS, and iOS crash reports show the stack traces for all running threads of your app at the time a crash occurred. The stack traces only contain memory addresses; not class names, methods, file names, or line numbers needed to understand the crashes.

To get the memory addresses translated you need to upload a dSYM package to App Center, which contains all information required for symbolication. You can learn more about symbolication from Apple’s official developer documentation.

The App Center Build and Distribution service can automatically generate a valid dSYM and source map .zip file and upload the file to the Diagnostics service. If you use App Center to build and auto distribute your app to your end users, you don't need to manually obtain and upload the symbol files.

Unsymbolicated crashes

Unsymbolicated crashes are displayed in the App Center Diagnostics section so you can view some details even before uploading symbols. The missing symbols from these crashes will be shown in the "unsymbolicated" tab. If the missing symbols are uploaded, the unsymbolicated crash group will be replaced by a symbolicated crash group.

Finding the .dSYM bundle

1. In Xcode, open the Window menu, then select Organizer.
2. Select the Archives tab.
3. Select your app in the left sidebar.
4. Right-click on the latest archive and select Show in Finder.
5. Right-click the .xcarchive file in Finder and select Show Package Contents.
6. You should see a folder named dSYMs that contains your dSYM bundle.
7. Create a zip file of the dSYM bundle.

If you're using Visual Studio instead of Xcode, see Where can I find the dSYM file to symbolicate iOS crash logs? to find the dSYM file.

Uploading symbols

App Center Portal

1. Log into App Center and select your app.
2. In the left menu, navigate to the Diagnostics section and select Symbols.
3. In the top-right corner, click Upload symbols and upload the file.
4. After the symbols are indexed by App Center, crashes will be symbolicated for you.

React Native iOS apps

To obtain symbol files for React Native iOS files, create a ZIP file with the dSYM package on your Mac and the JavaScript source map of your app. The source map should be named index.ios.map. The commands below will generate the source map for release builds:

react-native bundle --entry-file index.ios.js --platform ios --dev false --reset-cache --bundle-output unused.jsbundle --sourcemap-output index.ios.map

App Center API

The process for uploading symbols through the API involves a series of three API calls: one to allocate space on our backend, one to upload the file, and one to update the status of the upload. The body of the first API call should set symbol_type to Apple.

1. Trigger a POST request to the symbol_uploads API. This call allocates space on our backend for your file and returns a symbol_upload_id and an upload_url property.

curl -X POST 'https://api.appcenter.ms/v0.1/apps/{owner_name}/{app_name}/symbol_uploads' \
    -H 'accept: application/json' \
    -H 'X-API-Token: {API TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{JSON BODY}'

2. Using the upload_url property returned from the first step, make a PUT request with the header: "x-ms-blob-type: BlockBlob" and supply the location of your file on disk. This call uploads the file to our backend storage accounts. Learn more about PUT Blob request headers .

curl -X PUT '{upload_url}' \
    -H 'x-ms-blob-type: BlockBlob' \
    --upload-file '{path to file}'

3. Make a PATCH request to the symbol_uploads API using the symbol_upload_id property returned from the first step. In the body of the request, specify whether you want to set the status of the upload to committed (successfully completed) the upload process, or aborted (unsuccessfully completed).

curl -X PATCH 'https://api.appcenter.ms/v0.1/apps/{owner_name}/{app_name}/symbol_uploads/{symbol_upload_id}' \
    -H 'accept: application/json' \
    -H 'X-API-Token: {API TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{ "status": "committed" }'

Note

The symbol uploads API doesn't work for files that are larger than 256MB. Use the App Center CLI to upload these files. You can install the App Center CLI by following the instructions in our App Center CLI repo.

App Center CLI

You can also use the CLI to upload symbol files:

appcenter crashes upload-symbols --symbol {symbol file}

Bitcode

Bitcode was introduced by Apple to allow apps sent to the App Store to be recompiled by Apple itself and apply the latest optimization. If Bitcode is enabled, the symbols generated for your app in the store will be different than the ones from your own build system.

App Center crash reporting doesn't completely support the symbolication of crashes from bitcode-enabled apps yet. In the meantime, we advise that you disable bitcode. Disabling bitcode significantly simplifies symbols management and currently doesn't have any known downsides for iOS apps.

Disable bitcode for your app

1. In Xcode, open your project settings by clicking on the top-level element in the Project Navigator
2. Go to the Build Settings page
3. Search for bitcode
4. In the result, change the value from Yes to No
5. Rebuild your app

With these simple steps, App Center crash reporting will behave as usual.

Retrieve symbols for bitcode enabled apps

If you want to keep bitcode enabled, you can download the proper dSYM files by following these steps:

1. Open the Xcode's Organizer
2. Select the specific archive of your app that you uploaded to iTunes Connect
3. Click on the "Download dSYMs" button. This step will insert the Bitcode compiled dSYM files into the original archive.
4. Upload the symbols to the corresponding app and version in App Center

If the Xcode organizer doesn't provide any new symbols, you must download the dSYM files from the iTunes Connect portal by following these steps:

1. Select your app in the iTunes Connect portal
2. Select the Activity tab on top
3. Select the build version of your app that has the missing symbols
4. Click the Download dSYM link
5. Upload the downloaded file to App Center. This file contains the symbols required for App Center to symbolicated your crashes.

Troubleshooting symbol issues

If your crashes still appear unsymbolicated after uploading symbols and disabling bitcode, it might be because the uploaded dSYM files don't match the ones required by App Center. When you upload dSYM files, App Center matches them to the right app version based on their UUIDs.

You can double check whether your dSYM files have the right UUIDs by using a CLI tool called dwarfdump.

1. Find the UUID in the dSYM file:

dwarfdump --u CrashProbeiOS.app.dSYM

2. The result should look something like this:

UUID:ADF53C85-4638-3EFF-A33C-42C13A18E915 (armv7)CrashProbeiOS.app.dSYM/Contents/Resources/DWARF/CrashProbeiOS
UUID:D449E33D-7E74-379D-8B79-15EE104ED1DF (arm64)CrashProbeiOS.app.dSYM/Contents/Resources/DWARF/CrashProbeiOS

3. Double check if the UUID returned matches the UUIDs shown in the debug symbols dialog:

Ignoring symbols

When App Center doesn't have all the symbol files to fully symbolicate crash reports, the crashes are listed in the Unsymbolicated tab. The required symbols are uploaded from this page if you have access to them.

If you can't upload the symbols, you can mark them as Ignored by selecting rows in the table and clicking the Ignore versions button. This button tells App Center to process the crashes and symbolicate them as fully as possible with the symbols on file. Once they've finished processing, they'll appear in the Crashes tab partially symbolicated. New crashes that also depend on those same symbol IDs marked as ignored will bypass the Unsymbolicated tab as they come in and flow through the system.