# 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](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-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-cli)
* [Sentry Fastlane Plugin](#sentry-fastlane-plugin)
* [Xcode Build Phase](#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](https://betterprogramming.pub/info-plist-is-missing-in-xcode-13-heres-how-to-get-it-back-1a7abf3e2514).

## [Sentry-cli](#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 stack traces. This feature is called [source context](/platforms/apple/guides/macos/data-management/debug-files/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

```bash
sentry-cli debug-files upload --auth-token sntrys_YOUR_TOKEN_HERE \
  #  source-context
  --include-sources \
  #  source-context
  --org example-org \
  --project example-project \
  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](/cli/configuration/).

## [Sentry Fastlane Plugin](#sentry-fastlane-plugin)

If you're already using Fastlane, you can use the [Sentry Fastlane plugin](https://github.com/getsentry/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](/platforms/apple/guides/macos/data-management/debug-files/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.

```ruby
sentry_debug_files_upload(
  auth_token: 'sntrys_YOUR_TOKEN_HERE',
  org_slug: 'example-org',
  project_slug: 'example-project',
  #  source-context
  include_sources: true, # Optional. For source context.
  #  source-context
)
```

##### 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:

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

## [Xcode Build Phase](#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](/cli/installation/).
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 stack traces. This feature is called [source context](/platforms/apple/guides/macos/data-management/debug-files/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.

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

if which sentry-cli >/dev/null; then
export SENTRY_ORG=example-org
export SENTRY_PROJECT=example-project
export SENTRY_AUTH_TOKEN=sntrys_YOUR_TOKEN_HERE
ERROR=$(sentry-cli debug-files upload \
#  source-context
--include-sources \
#  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.

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

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

4. Set `ENABLE_USER_SCRIPT_SANDBOXING` in your Xcode project settings to `NO`.

[![enable-user-script-sandboxing](/_next/image/?url=%2Fmdx-images%2Fenable_user_script_sandboxing-77UJYS2Q.png%231056x148\&w=3840\&q=75)](/mdx-images/enable_user_script_sandboxing-77UJYS2Q.png)

##### 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:

```bash
export SENTRY_URL=https://mysentry.invalid/
```
