---
title: "Uploading Debug Symbols"
description: "Learn more about how to upload debug symbols for iOS."
url: https://docs.sentry.io/platforms/apple/guides/watchos/dsym/
---

# Uploading Debug Symbols | Sentry for watchOS

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](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#sentry-cli)
* [Sentry Fastlane Plugin](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#sentry-fastlane-plugin)
* [Xcode Build Phase](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#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](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#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](https://docs.sentry.io/platforms/apple/guides/watchos/data-management/debug-files/source-context.md). 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 ___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/](https://docs.sentry.io/cli/installation.md).

For more info on `sentry-cli` configuration visit the [Sentry CLI configuration docs](https://docs.sentry.io/cli/configuration.md).

## [Sentry Fastlane Plugin](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#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](https://docs.sentry.io/platforms/apple/guides/watchos/data-management/debug-files/source-context.md). 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: '___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](https://docs.sentry.io/platforms/apple/dsym.md#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:

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

## [Xcode Build Phase](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#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](https://docs.sentry.io/cli/installation.md).
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](https://docs.sentry.io/platforms/apple/guides/watchos/data-management/debug-files/source-context.md). 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=___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.

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/${EXECUTABLE_NAME}
```

4. 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:

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

## [Migration Guide](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#migration-guide)

### [Migrating from Sentry Fastlane Plugin 1.x to 2.0.0](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#migrating-from-sentry-fastlane-plugin-1x-to-200)

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.

#### [Removed Actions](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#removed-actions)

The following actions have been removed and must be replaced:

**`sentry_upload_dsym`** → Use `sentry_debug_files_upload` instead:

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

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

```ruby
# 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'
)
```

#### [Removed Parameters](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#removed-parameters)

**`api_key`** → Use `auth_token` instead:

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

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

```ruby
# 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):

```ruby
# 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`

```ruby
# 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
)
```

#### [Changed Default Behavior](https://docs.sentry.io/platforms/apple/guides/watchos/dsym.md#changed-default-behavior)

**`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).

```ruby
# 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](https://github.com/getsentry/sentry-cli/releases/tag/3.0.0) and the [plugin changelog](https://github.com/getsentry/sentry-fastlane-plugin/blob/master/CHANGELOG.md).