Instabug needs your project's dSYM in order to be able to symbolicate crash reports from your app. If you are seeing a message saying "This crash is not symbolicated" on your Instabug dashboard, that means Instabug doesn't have your project's dSYM and won't be able to symbolicate crashes.

In this page, we will detail how you can find your dSYMs, upload your dSYMs, and what to do if you have __hidden in your stack traces.

Finding dSYMs

There are two types of dSYM files: required and optional.

Required dSYM files are used to symbolicate your application's frames. In the screenshot below, only the required dSYM is missing.

Optional dSYM files are used to symbolicate the frames belonging to any plugin or library you are using.

To find your project's dSYM, run the command shown to you on your Instabug dashboard.

mdfind "com_apple_xcode_dsym_uuids == your-UUID-here"

Uploading dSYMs

After you have located your project's dSYM, you can either upload it manually or by using the upload script included in the SDK.

Manually

1. Compress the dSYM file you have located on your machine into a zip file.
2. Go to Upload dSYMs in the Settings menu of your Instabug dashboard.
3. Upload the compressed file.

Automatically

All Builds

Instabug has a shell script that can automatically upload your project's dSYM during the build process. To use it, go to your project's Build Phases tab and add a new Run Script Build Phase, then add the following to it.

#- -- SCRIPT BEGIN - --
# SKIP_SIMULATOR_BUILDS=1
  SCRIPT_SRC=$(find "$PROJECT_DIR" -name 'Instabug_dsym_upload.sh' | head -1)
  if [ ! "${SCRIPT_SRC}" ]; then
    echo "Instabug: err: script not found. Make sure that you're including InstabugResources.bundle in your project directory"
    exit 1
  fi
  # APP_TOKEN="YOUR-APP-TOKEN-HERE"
  source "${SCRIPT_SRC}"
#- -- SCRIPT END - --

#- -- SCRIPT BEGIN - --
# SKIP_SIMULATOR_BUILDS=1
  SCRIPT_SRC=$(find "$BUILT_PRODUCTS_DIR" -name 'Instabug_dsym_upload.sh' | head -1)
  if [ ! "${SCRIPT_SRC}" ]; then
    echo "Instabug: err: script not found. Make sure that you're including InstabugResources.bundle in your project directory"
    exit 1
  fi
  # APP_TOKEN="YOUR-APP-TOKEN-HERE"
  source "${SCRIPT_SRC}"
#- -- SCRIPT END - --

• Make sure you replace YOUR-APP-TOKEN-HERE with your actual app token (found under SDK Integration in the Settings menu of your Instabug dashboard and uncomment the line.
• Uncomment SKIP_SIMULATOR_BUILDS=1 if you want to run this script when building on a device only.

There are two ways to use the script:

Build Settings (Recommended)

You will need to add the previous script to the Build > Post-actions.

Make sure to select your app to provide build settings to script:

Archives Only (Not Recommended)

📘

Make sure the build phase is the last one in the build phases

🚧

Please use this method only if you need to run the script when building a specific target not an app

Go to your project's Build Phases tab and add a new Run Script Build Phase, then add the following to it.

You will need to add the script to the Archive > Post-actions.

Make sure to select your app to provide build settings to script:

📘

XCode 15 or Above

If you’re using Xcode 15 or above, please make sure you follow the below steps to avoid build errors

1. Select the Target
   1. In the Project Navigator on the left, click on your project name (the top-level icon).
   2. Select the specific Target you wish to modify.
2. Access Build Settings
   1. In the main editor, go to the Build Settings tab.
   2. (Optional) Click All or Levels to see all settings.
3. Disable Flags in Build Settings
   1. In the search field (top-right corner), enter ENABLE_USER_SELECTED_FILES.
      1. Locate the setting and set it to NO.
   2. Next, search for ENABLE_USER_SCRIPT_SANDBOXING.
      1. Locate the setting and set it to NO.

Through Fastlane

You can use our official Instabug plugin to upload your dSYM files to your Instabug dashboard if you're using Fastlane. This section explains how to do just that.

1. If you don’t have Fastlane, open your terminal and navigate to your project then run the next command to install it:

gem install fastlane

2. If you don’t have the latest Fastlane version installed, run the following command:

fastlane init

3. Install the Official Instabug Plugin

fastlane add_plugin instabug_official

4. You can use this plug-in with gym to upload dSYMs generated from the build:

lane :build do
  gym
  instabug_official(api_token: "<Instabug token>")
end

5. If you prefer to pass the dSYM file paths manually:

instabug_official(api_token: "<Instabug token>", dsym_array_paths: ["./App1.dSYM.zip", "./App2.dSYM.zip"])

Using API

Additionally, we have an API endpoint that you can use to upload your dSYMs directly from the console. The dSYMs must be uploaded as a zip file.

URL:
https://api.instabug.com/api/sdk/v3/symbols_files
METHOD:
POST
PARAMS:
symbols_file
os (android, ios,,,)
application_token

Example:
curl -X POST "https://api.instabug.com/api/sdk/v3/symbols_files" -F os=iOS -F symbols_file=@"{DSYM_ZIP_PATH} " -F application_token="{APPLICATION_TOKEN}"

Debug Builds

To enable crash symbolication for debug builds, you have to change your project's build settings to generate dSYM files for debug builds.

To do so, select your target in Xcode then go to Build Settings, search for Debug Information Format, and change its value to DWARF with dSYM File.

Hidden in Stack Traces

If you have stack traces that contain frames that have __hidden instead of a symbol name, this is because you did not share your app's symbols with Apple while uploading a build to iTunes Connect.

To make sure stack traces of crashes from your app do not contain any hidden symbols, always check Upload your app's symbols to receive symbolicated reports from Apple when uploading a new build.

With this option unchecked, dSYMs generated by iTunes Connect for apps that have Bitcode enabled will be obfuscated. To de-obfuscate those dSYMs, download them from iTunes Connect, then use the following command (substituting your archive and dSYM paths):

xcrun dsymutil -symbol-map ~/Library/Developer/Xcode/Archives/2017-11-23/MyGreatApp\ 11-23-17\,\ 12.00\ PM.xcarchive/BCSymbolMaps ~/Downloads/dSYMs/3B15C133-88AA-35B0-B8BA-84AF76826CE0.dSYM

Run this command for each dSYM file inside the dSYMs folder you downloaded from iTunes Connect. After that is complete, upload the updated dSYMs to Instabug to get fully symbolicated stack traces.

🚧

The uploaded dSYM files are only applied to production builds and not beta builds.