---
title: "Debug Symbols Uploading"
description: "Learn how the Unreal Engine SDK handles debug symbols upload."
url: https://docs.sentry.io/platforms/unreal/configuration/debug-symbols/
---

# Debug Symbols Uploading for Unreal Engine

Sentry requires [debug information files](https://docs.sentry.io/platforms/unreal/data-management/debug-files.md) to symbolicate crashes. The Unreal Engine SDK provides an automated upload functionality for those symbol files that relies on the [Sentry CLI](https://cli.sentry.dev). This is done automatically, so running the Sentry CLI manually isn't required. The symbol upload happens during the execution of `PostBuildSteps`, as specified in the `Sentry.uplugin` file. The Sentry CLI executables for Windows (x64), macOS (Apple silicon and Intel), and Linux (x64) are included as part of the Unreal Engine SDK package. They can also be downloaded manually via the settings menu if the plugin was installed from the UE Marketplace.

For Android, debug symbols upload is handled by [Sentry Android Gradle Plugin](https://docs.sentry.io/platforms/android/configuration/gradle.md). By default, it bumps Gradle version to 7.5 automatically, however one can fallback to using its legacy version in case compatibility issues with other third-party plugins arise.

## [Automatic Upload](https://docs.sentry.io/platforms/unreal/configuration/debug-symbols.md#automatic-upload)

The automated debug symbols upload is disabled by default and requires configuration. To configure it, navigate to **Project Settings > Plugins > Sentry**, then enable "Upload debug symbols automatically".

Alternatively, debug symbol upload can be enabled by setting the `SENTRY_UPLOAD_SYMBOLS_AUTOMATICALLY` environment variable to `True`. This can be especially helpful in CI/CD environments where manual configuration is impractical.

Sentry will upload debug symbols only for build configurations and target types that are enabled in the plugin settings under **Core > Advanced** (**Enable for Build Configurations** and **Enable for Build Target Types**).

The Sentry CLI requires you to specify the organization and project to work with as well as a token to authenticate with Sentry. The Unreal Engine SDK provides two ways to configure these settings - either by using a properties file (default) or environment variables. Environment variables take priority over the values in the properties file.

### [Properties File](https://docs.sentry.io/platforms/unreal/configuration/debug-symbols.md#properties-file)

To configure the upload using the properties file, enter the [Auth Token](https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/), Organization Slug, and Project Name. Note, that the Unreal Engine SDK automatically creates a `sentry.properties` file at the root of your project directory to store the configuration. This configuration file should **never** be made publicly available.

### [Environment Variables](https://docs.sentry.io/platforms/unreal/configuration/debug-symbols.md#environment-variables)

The upload can be configured by setting the following environment variables, which are automatically picked up during the debug symbols upload. If the properties file isn't found, the environment variables are the only source of these settings. If it's found, each variable that has a value takes priority over the matching value in the properties file:

```bash
export SENTRY_ORG=<your-org-slug>
export SENTRY_PROJECT=<your-project-slug>
export SENTRY_AUTH_TOKEN=<your-sentry-auth-token>
```

## [Manual Upload Using Sentry CLI](https://docs.sentry.io/platforms/unreal/configuration/debug-symbols.md#manual-upload-using-sentry-cli)

To upload debug symbols to Sentry manually, run the Sentry CLI through the command line. You can either use the provided executables from within the package, or follow the [Sentry CLI documentation](https://cli.sentry.dev/install) to make it available globally. To upload debug symbols, set the organization, project, and auth token, then run the following command:

```bash
export SENTRY_ORG=<your-org-slug>
export SENTRY_PROJECT=<your-project-slug>
export SENTRY_AUTH_TOKEN=<your-sentry-auth-token>

sentry debug-files upload PATH_TO_SYMBOLS
```

## [Debug symbols for macOS and iOS](https://docs.sentry.io/platforms/unreal/configuration/debug-symbols.md#debug-symbols-for-macos-and-ios)

Sentry requires [*dSYM files*](https://docs.sentry.io/platforms/unreal/data-management/debug-files/file-formats.md#mach-o-and-dsym) to fully symbolicate your stack traces for macOS/iOS games. To ensure that the debug symbols are generated and can be processed by the Sentry Unreal plugin during the execution of `PostBuildSteps`, add the following build settings to your project `.Target.cs` file:

```csharp
// For Mac
MacPlatform.bUseDSYMFiles = true;

// For iOS
IOSPlatform.bGeneratedSYM = true;
```

Unreal Engine 5.3 and newer supports [Modernized Xcode Workflow](https://dev.epicgames.com/documentation/en-us/unreal-engine/using-modern-xcode-in-unreal-engine-5.3-and-newer) which aligns more closely with standard Apple development practices. In this case, symbol upload can be handled during the custom [Xcode Build Phase](https://docs.sentry.io/platforms/apple/guides/macos/dsym.md#xcode-build-phase).
