Uploading Debug Symbols

Sentry requires a dSYM upload to symbolicate your crash logs. The symbolication process unscrambles Apple’s crash logs to reveal the function, file names, and line numbers of the crash. Upload the dSYM file using either sentry-cli, the Fastlane action, or set up the Sentry App Store Connect integration for Bitcode builds. Every solution requires a Sentry Auth Token with the correct permissions. You can create one here.

With Bitcode

If Bitcode is enabled in your project, dSYM files will only be available after App Store Connect finishes processing the build. Sentry can fetch dSYM files automatically as they become available from App Store Connect when setting up the App Store Connect integration. Alternatively, the dSYM files can be downloaded either with Fastlane or manually, and uploaded with Fastlane or sentry-cli.

Using App Store Connect

When you use the App Store Connect integration, Sentry will automatically discover and fetch dSYM files for Bitcode builds as they become available on App Store Connect. These dSYM files however contain obfuscated symbol names and paths. An additional BCSymbolMap file needs to be uploaded to provide properly symbolicated crash reports. These BCSymbolMap files can be uploaded using either sentry-cli or Fastlane.

To configure the integration, go to [Project] > Settings > Debug Files and add "App Store Connect" in the "Custom Repositories" section.

Once the integration is set up it will ensure that new builds are detected and fetched within an hour of being available on App Store Connect.

Setting up an App Store Connect custom repository requires an App Store Connect API Key.

Follow the documentation on Creating API Keys for App Store Connect API and provide the Issuer, Key ID, and Private Key. The API Key needs to have the Developer role in order to fetch build details.

Invalid Credentials

If your App Store Connect API key is revoked on the Apple side, the Sentry custom repository using this key's credentials will no longer be able to discover and fetch dSYM files and the following warnings will be displayed in the Senty's User Interface:

Issue Details

Project Settings

Custom Repositories

Upload BCSymbolMaps Using Fastlane

As dSYM download will be handled by sentry, it is not necessary to use the download_dsyms or sentry_upload_dsym commands. Instead, use the sentry_upload_dif command to upload the BCSymbolMap.

sentry_upload_dif(
  auth_token: 'YOUR_AUTH_TOKEN',
  org_slug: 'example-org'
  project_slug: 'example-project',
  path: '/path/to/files' # Optional. Well default to '.' when no value is provided.
)

When using the upload_to_testflight action, it is recommended to pass the skip_waiting_for_build_processing parameter to speed up the action.

Upload BCSymbolMaps Using sentry-cli

The sentry-cli upload-dif command will automatically find and upload all BCSymbolMap files, given the path to the app's .xcarchive.

Using Fastlane

Use the Fastlane action, download_dsyms, to download the dSYMs from App Store Connect and upload to Sentry. The dSYM won’t be generated until after the app is done processing on App Store Connect so this should be run in its own lane.

lane :upload_symbols do
  download_dsyms # this is the important part
  sentry_upload_dsym(
    auth_token: 'YOUR_AUTH_TOKEN',
    org_slug: 'example-org',
    project_slug: 'example-project',
  )
end

url: 'https://mysentry.invalid/'

Using sentry-cli

Download the dSYM from App Store Connect. After that, you can upload the dSYM using sentry-cli.

1. Open Xcode Organizer, go to your app, and click “Download dSYMs...”
2. Login to App Store Connect, go to your app, go to “Activity", click the build number to go into the detail page, and click “Download dSYM”

Afterwards manually upload the symbols with sentry-cli:

sentry-cli --auth-token YOUR_AUTH_TOKEN upload-dif --org example-org --project example-project PATH_TO_DSYMS

export SENTRY_URL=https://mysentry.invalid/

Without Bitcode

When not using Bitcode you can directly upload the symbols to Sentry as part of your build.

Using Fastlane

If you are already using Fastlane you can use it in this situation as well:

lane :build do
  gym # building your app
  sentry_upload_dsym(
    auth_token: 'YOUR_AUTH_TOKEN',
    org_slug: 'example-org',
    project_slug: 'example-project',
  )
end

api_host: 'https://mysentry.invalid/'

Uploading Symbols with sentry-cli

Your project’s dSYM can be upload during the build phase as a “Run Script”. For this you need to set the DEBUG_INFORMATION_FORMAT to be DWARF with dSYM File. By default, an Xcode project will only have DEBUG_INFORMATION_FORMAT set to DWARF with dSYM File in Release so make sure everything is set in your build settings properly.

You need to have an Auth Token for this to work. You can create an Auth Token here.

1. Download and install sentry-cli
2. You will need to copy the script below into a new Run Script and set your AUTH_TOKEN, ORG_SLUG, and PROJECT_SLUG

if which sentry-cli >/dev/null; then
export SENTRY_ORG=example-org
export SENTRY_PROJECT=example-project
export SENTRY_AUTH_TOKEN=YOUR_AUTH_TOKEN
ERROR=$(sentry-cli upload-dif "$DWARF_DSYM_FOLDER_PATH" 2>&1 >/dev/null)
if [ ! $? -eq 0 ]; then
echo "warning: sentry-cli - $ERROR"
fi
else
echo "warning: sentry-cli not installed, download from https://github.com/getsentry/sentry-cli/releases"
fi

3. If you are using Xcode 10 or newer, you also need to add the following line to the Input Files section in the Run Script from step 2:

${DWARF_DSYM_FOLDER_PATH}/${DWARF_DSYM_FILE_NAME}/Contents/Resources/DWARF/${TARGET_NAME}

If the upload never completes you can try to pass --force-foreground to the Sentry CLI command in the build script. This is possibly due to a bug we are investigating.

export SENTRY_URL=https://mysentry.invalid/