Uploading Debug Symbols

Sentry requires dSYMs (debug information files) to symbolicate your stacktraces. The symbolication process unscrambles the stacktraces to reveal the function, file names, and line numbers of the crash.

Every solution requires a Sentry Auth Token. We recommend using internal integrations for managing Auth Tokens. Create a new internal integration with the permission project:read&write, if you don't have one already. After saving it, you can copy the Auth Token from the integration page.

To view uploaded dSYMs in your project, select an existing project from the "Projects" page, then go to Settings > Debug Files. You can upload dSYMs using:

• sentry-cli
• Sentry Fastlane Plugin
• Xcode Build Phase
• App Store Connect Integration

Sentry-cli

Use the sentry-cli debug-files upload command to upload dSYMs to Sentry. The command will recursively scan the provided folders or ZIP archives. Files that have already been uploaded will be skipped automatically.

Sentry can display snippets of your code next to the event stacktraces. This feature is called source context. When setting the --include-sources option, sentry-cli will scan your debug files to find references to the source code files, resolve them in the local file system, bundle them up, and upload them to Sentry.

sentry-cli debug-files upload --auth-token YOUR_AUTH_TOKEN \
  --org example-org \
  --project example-project \
  PATH_TO_DSYMS

Visit the sentry-cli docs for more information.

Sentry Fastlane Plugin

If you're already using Fastlane, you can use the Sentry Fastlane plugin to upload your dSYMs to Sentry.

Sentry can display snippets of your code next to event stacktraces. This feature is called source context. When setting the include_sources parameter to true, the Fastlane plugin will scan your debug files to find references to the source code files, resolve them in the local file system, bundle them up, and upload them to Sentry.

sentry_upload_dif(
  auth_token: 'YOUR_AUTH_TOKEN',
  org_slug: 'example-org',
  project_slug: 'example-project',
  include_sources: true, # Optional. For source context.
)

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

Xcode Build Phase

Your project's dSYM can be uploaded during Xcode's build phase as a Run Script. To do this, set the DEBUG_INFORMATION_FORMAT to DWARF with a dSYM file. By default, an Xcode project will only have DEBUG_INFORMATION_FORMAT set to DWARF with a dSYM file in release, so make sure everything is properly set up in your build settings.

Follow these steps to upload the debug symbols:

1. Download and install sentry-cli.
2. Copy the script below into a new Run Script and set your AUTH_TOKEN, ORG_SLUG, and PROJECT_SLUG.

Sentry can display snippets of your code next to the event stacktraces. This feature is called source context. When setting the --include-sources option, sentry-cli will scan your debug files to find references to the source code files, resolve them in the local file system, bundle them up, and upload them to Sentry. Simply change sentry-cli debug-files upload to sentry-cli debug-files upload --include-sources in the copied script.

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 debug-files upload "$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. 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}

export SENTRY_URL=https://mysentry.invalid/

App Store Connect Integration

When you use the App Store Connect integration, Sentry will automatically discover and fetch dSYMs for builds as they become available on App Store Connect.

To configure the integration, select an existing project from the "Projects" page, then go to 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. In order to be able to fetch build details, your API Key needs to be assigned the Developer role.

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. You'll see the following warnings in Sentry's user interface:

Issue Details

Project Settings

Custom Repositories

When using Fastlane's upload_to_testflight action, it's recommended to pass the skip_waiting_for_build_processing parameter to speed up the action.

Bitcode

If you’re using Xcode 13, you’ll need to download the dSYMs from App Store Connect after it finishes processing your build, and then upload them to Sentry using one of the methods below:

• Download Fastlane's download_dsyms action and then upload the dSYMs with the Sentry Fastlane plugin.
• Use the Sentry App Store Connect integration, which fetches the dSYMS directly from App Store Connect.
• Download manually from App Store Connect:
  • Open Xcode Organizer, go to your app, and click Download dSYMs...
  • Log in to App Store Connect, go to your app > “Activity".
  • Click the build number to go into the "detail" page, and click Download dSYM.
  • Manually upload the dSYMs with sentry-cli.

These dSYMs contain obfuscated symbol names and paths. You must upload the BCSymbolMap file stored in your xcarchive so Sentry can properly symbolicate your crash reports. You can do this by using the debug-files upload command of either sentry-cli or the Sentry Fastlane plugin, which will automatically find and upload all BCSymbolMap files when specifying the path to the app's xcarchive.