Upload Unity symbols for Android

When you build Android games with Unity using IL2CPP, a symbol ZIP file is generated containing the symbols used in your C# code as well as the Unity framework itself. These files should be uploaded, along with any ProGuard, DexGuard, or R8 mappings and NDK symbol files in order to show full stacktraces in your dashboard.

For installation instructions for the BugSnag CLI, please see our Installation guide.


The unity-android command uploads the IL2CPP symbols from the .symbols.zip file produced by the Unity build (see Unity documentation for more information) to the NDK symbol API.

$ bugsnag-cli upload unity-android <path> --aab-path <aab-path>

Where <path> is either the symbols ZIP file or the directory containing it. This defaults to the current directory if omitted.

The command will also attempt to upload Android mapping and symbols files from the Android App Bundle (AAB) produced by the Gradle build. If an AAB is located in the same directory as the Unity symbols file (or at the location provided in --aab-path) then the manifest inside it will be used to provide your app’s build information required for the symbol upload.

Example usage

Assuming the symbols ZIP and generated AAB are in the app build directory, the simplest way to run the command is to specify this directory along with the project API key:

$ bugsnag-cli upload unity-android /path/to/build/directory \
    --api-key my-api-key

Alternatively you can provide the symbols ZIP and AAB file paths specifically:

$ bugsnag-cli upload unity-android /path/to/my-game.symbols.zip \
    --aab-path /path/to/my-game.aab \    
    --api-key my-api-key

Available options

AAB path (--aab-path)

The path to the generated .aab file to upload with the Unity symbols.

API key (--api-key)

Your project’s API key. This defaults to the value of com.bugsnag.android.API_KEY in your app’s manifest file, if found.

You can find your API key in Project Settings from your BugSnag dashboard.

Application ID (--application-id)

The unique application ID, usually the package name, of the app. This defaults to the value of Package in your app’s manifest file, if found.

Dry run (--dry-run)

Used to see the files and options that would be uploaded without actually sending them to the BugSnag endpoint.

Fail on upload (--fail-on-upload)

Whether to stop any further uploads if a file fails to upload successfully. By default the command attempts to upload all files.

Overwrite (--overwrite)

Whether to ignore and overwrite existing uploads with same identifier. By default the command will fail if a matching file exists.

Project root (--project-root)

Path to strip from the beginning of source file names referenced in stacktraces when displayed as an error in your dashboard. This will default to your project’s root directory if the command has detected one, otherwise it’s empty.

Retries (--retries)

The number of retry attempts before failing an upload. By default it is only attempted once.

Timeout (--timeout)

The number of seconds to wait before failing an upload attempt. By default the upload is given 300s (5 mins).

Upload API root URL (--upload-api-root-url)

The BugSnag On-premise upload server hostname, optionally containing port number. The command will append the appropriate path to access the correct BugSnag API upload endpoint.

Version code (--version-code)

The version code of this build of the app. This defaults to the value of VersionCode in your app’s manifest file, if found.

Version name (--version-name)

The version of the app. This defaults to the value of VersionName in your app’s manifest file, if found.