Uploading Debug Symbols

Learn more about how to upload debug symbols for iOS.

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

Every solution requires a Sentry Auth Token. You can create tokens on the Organization Tokens settings 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

Starting with Xcode 13, newly generated projects don't automatically create a required Info.plist configuration file. If this is your situation, please read Info.plist Is Missing in Xcode 13 — Here's How To Get It Back.

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 stack traces. 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.

For this to work, your project settings for DEBUG_INFORMATION_FORMAT must be set to DWARF with dSYM File, which is the default for release builds but not for debug builds.

You can also upload your code for source context. This feature allows Sentry to display snippets of your code next to the event stack traces.

Source Context

Copied

sentry-cli debug-files upload --auth-token ___ORG_AUTH_TOKEN___ \
  # ___PRODUCT_OPTION_START___ source-context
  --include-sources \
  # ___PRODUCT_OPTION_END___ source-context
  --org ___ORG_SLUG___ \
  --project ___PROJECT_SLUG___ \
  PATH_TO_DSYMS

You can find installation instructions for Sentry CLI https://docs.sentry.io/cli/installation/.

For more info on sentry-cli configuration visit the Sentry CLI configuration docs.

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 stack traces. 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.

Copied

sentry_debug_files_upload(
  auth_token: '___ORG_AUTH_TOKEN___',
  org_slug: '___ORG_SLUG___',
  project_slug: '___PROJECT_SLUG___',
  # ___PRODUCT_OPTION_START___ source-context
  include_sources: true, # Optional. For source context.
  # ___PRODUCT_OPTION_END___ source-context
)

Breaking Changes in Version 2.0.0

The Sentry Fastlane plugin version 2.0.0 includes breaking changes due to the sentry-cli 3.0.0 upgrade. If you're upgrading from version 1.x, see the migration guide for details.

On Prem

By default fastlane will connect to sentry.io. For on-prem you need to provide the url parameter to instruct the tool to connect to your server:

Copied

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

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:

Download and install sentry-cli.
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 stack traces. 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.

For this to work, your project settings for DEBUG_INFORMATION_FORMAT must be set to DWARF with dSYM File, which is the default for release builds but not for debug builds. If you don't want Sentry to upload your source code, remove the --include-sources argument from the copied script.

Warnings vs. Errors

Depending on your needs, you may want to emit warnings to the Xcode build log to let the build pass, or emit errors to fail it. For example, in a CI deployment where debug symbols may be harder to recover, and you might not realize symbols couldn't be symbolicated until after release, it might be better to fail the build.

Another option is to use warnings, and then set GCC_TREAT_WARNINGS_AS_ERRORS to YES in build settings for configurations you use to deploy to production.

Copied

if [[ "$(uname -m)" == arm64 ]]; then
    export PATH="/opt/homebrew/bin:$PATH"
fi

if which sentry-cli >/dev/null; then
export SENTRY_ORG=___ORG_SLUG___
export SENTRY_PROJECT=___PROJECT_SLUG___
export SENTRY_AUTH_TOKEN=___ORG_AUTH_TOKEN___
ERROR=$(sentry-cli debug-files upload \
# ___PRODUCT_OPTION_START___ source-context
--include-sources \
# ___PRODUCT_OPTION_END___ source-context
"$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

You can add --force-foreground argument to sentry-cli to help you debug any error that could happen during the upload process.

You also need to add the following line to the Input Files section in the Run Script from step 2:

Copied

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

Set ENABLE_USER_SCRIPT_SANDBOXING in your Xcode project settings to NO.

Self Hosted

By default sentry-cli will connect to sentry.io. For on-prem you need to export the SENTRY_URL environment variable to instruct the tool to connect to your server:

Copied

export SENTRY_URL=https://mysentry.invalid/

Version 2.0.0 of the Sentry Fastlane plugin includes breaking changes due to the sentry-cli 3.0.0 upgrade. Follow this guide to migrate your Fastfiles.

The following actions have been removed and must be replaced:

sentry_upload_dsym → Use sentry_debug_files_upload instead:

Copied

# Before (removed)
sentry_upload_dsym(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  dsym_path: '/path/to/dSYMs'
)

# After
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  path: '/path/to/dSYMs'
)

sentry_upload_dif → Use sentry_debug_files_upload instead:

Copied

# Before (removed)
sentry_upload_dif(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  path: '/path/to/files'
)

# After
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  path: '/path/to/files'
)

sentry_upload_file → Use specialized upload actions instead:

Copied

# Before (removed)
sentry_upload_file(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  version: '1.0.0',
  file: '/path/to/file.map'
)

# After - For source maps, use:
sentry_upload_sourcemap(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  version: '1.0.0',
  sourcemap: '/path/to/file.map'
)

api_key → Use auth_token instead:

Copied

# Before (removed)
sentry_debug_files_upload(
  api_key: '...',  # ❌ Removed
  org_slug: '...',
  project_slug: '...'
)

# After
sentry_debug_files_upload(
  auth_token: '...',  # ✅ Use auth_token
  org_slug: '...',
  project_slug: '...'
)

android_manifest_path in sentry_upload_proguard → Remove this parameter:

Copied

# Before (removed)
sentry_upload_proguard(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  android_manifest_path: '/path/to/AndroidManifest.xml'  # ❌ Removed
)

# After
sentry_upload_proguard(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...'
  # android_manifest_path parameter removed - no longer needed
)

force_foreground in sentry_debug_files_upload → Remove this parameter:

Copied

# Before (removed)
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  force_foreground: true  # ❌ Removed (was deprecated since v1.26.0)
)

# After
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...'
  # force_foreground parameter removed
)

ids in sentry_debug_files_upload → Renamed to id (singular):

Copied

# Before (renamed)
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  ids: 'abc123'  # ❌ Renamed
)

# After
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  id: 'abc123'  # ✅ Use id instead
)

Deprecated parameters in sentry_debug_files_upload → Remove these parameters:

The following parameters have been removed as they are no longer supported in sentry-cli v3:

info_plist
no_reprocessing
upload_symbol_maps

Copied

# Before (removed)
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  info_plist: '/path/to/Info.plist',  # ❌ Removed
  no_reprocessing: true,  # ❌ Removed
  upload_symbol_maps: true  # ❌ Removed
)

# After
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...'
  # info_plist, no_reprocessing, and upload_symbol_maps parameters removed
)

path parameter in sentry_debug_files_upload → Default behavior changed:

The path parameter now defaults to DSYM_OUTPUT_PATH from fastlane's lane context if available (set by actions like build_app or ipa), otherwise falls back to '.' (current directory).

Copied

# If you were relying on the previous behavior of always searching from current directory:
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...'
  # path defaults to DSYM_OUTPUT_PATH if available, otherwise '.'
)

# To maintain previous behavior (always search from current directory):
sentry_debug_files_upload(
  auth_token: '...',
  org_slug: '...',
  project_slug: '...',
  path: '.'  # Explicitly specify current directory
)

For more details, see the sentry-cli 3.0.0 release notes and the plugin changelog.

Was this helpful?

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").

How to contribute | Edit this page | Create a docs issue | Get support