Deobfuscate or symbolicate crash stack traces

This article is for new Play Console beta users. If you're looking for information about classic Play Console, go to the classic Play Console Help menu.

To learn more about the new Play Console beta, read our launch blog post.

Crashes and ANRs on Android produce a stack trace, which is a snapshot of the sequence of nested functions called in your program up to the moment it crashed. These snapshots can help you to identify and fix any problems in the source.

If your app or game was developed using Java and you use ProGuard to optimize and obfuscate your APK files, you can upload a ProGuard mapping file for each version of your app on the Play Console. If your app or game was developed using native code, like C++, you can upload a debug symbols file for each version of your app on the Play Console. This makes it easier to analyze and fix your crashes and ANRs.

Important: Only ReTrace-compatible mapping files are supported for deobfuscation of apps compiled in Java. This is the same format used by ProGuard or R8.

Step 1: Generate a deobfuscation or symbolication file

To deobfuscate or symbolicate your app's crashes and ANRs for a version of your app, you first need to generate the required files for the same version of your app. You must generate and upload a file for each new version of your app for deobfuscation or symbolication to work.

Java: Generate a ProGuard mapping file

To deobfuscate Java stack traces, you first need to generate a ProGuard mapping file. To learn how, go to the Google Developers site.

Native: Generate a debug symbols file

Android Gradle plugin version 4.1 and later

If your project builds an Android App Bundle, you can automatically include the debug symbols file in it. To include this file, add the following to your app's build.gradle file:

  • android.defaultConfig.ndk.debugSymbolLevel = 'FULL'

Note: There is a 300 MB limit for the debug symbols file. If your debug symbols footprint is too large, use SYMBOL_TABLE instead of FULL to decrease the file size.

If your project builds an APK, use the build.gradle build setting above to generate the debug symbols file separately. Manually upload the debug symbols file to the Google Play Console as described below in Step 2: Upload a deobfuscation or symbolication file. As part of the build process, the Android Gradle plugin outputs this file in the following project location:

  • app/build/outputs/native-debug-symbols/variant-name/native-debug-symbols.zip

Android Gradle plugin version 4.0 and earlier (and other build systems)

As part of the build process for an APK or Android App Bundle, the Android Gradle plugin keeps a copy of the unstripped libraries in a project directory. This directory follows a structure similar to this:

app/build/intermediates/cmake/universal/release/obj

├── armeabi-v7a/

│   ├── libgamenegine.so

│   ├── libothercode.so

│   └── libvideocodec.so

├── arm64-v8a/

│   ├── libgamenegine.so

│   ├── libothercode.so

│   └── libvideocodec.so

├── x86/

│   ├── libgamenegine.so

│   ├── libothercode.so

│   └── libvideocodec.so

└── x86_64/

    ├── libgameengine.so

    ├── libothercode.so

    └── libvideocodec.so

Note: If you use a different build system, you could modify it to store unstripped libraries in a directory with the required structure above.

  1. Zip up the contents of this directory:
    • $ cd app/build/intermediates/cmake/universal/release/obj
    • $ zip -r symbols.zip .
  2. Manually upload the symbols.zip file to the Play Console as described below in Step 2: Upload a deobfuscation or symbolication file.

There is a 300 MB limit for the debug symbols file. If your file is too big, it’s likely because your .so files contain a symbol table (function names), and also DWARF debugging info (files names and lines of code). These are not needed to symbolicate your code, and can be removed by running this command:

  • $OBJCOPY --strip-debug lib.so lib.so.sym

Note: $OBJCOPY points to the specific version for the ABI you're stripping, for example:ndk-bundle/toolchains/aarch64-linux-android-4.9/prebuilt/linux-x86_64/bin/aarch64-linux-android-objcopy

Step 2: Upload a deobfuscation or symbolication file

To deobfuscate or symbolicate your app's crashes and ANRs for a version of your app, you must upload the deobfuscation or symbolication files for each version of your app.

Important: This step is only required for developers using APKs. If you’re using an Android App Bundle and Android Gradle plugin version 4.1 or later, then there's nothing you need to do. We'll automatically grab the deobfuscation file from the bundle and you can skip to Step 3: View deobfuscated crash stack traces. You can learn more about app bundles on the Android Developers site.

Upload files using the Play Console

To upload a deobfuscation or symbolication file:

  1. Open the Play Console.
  2. Select an app.
  3. On the left menu, select Release > Devices and versions> App bundle explorer.
  4. Using the picker in the top-right-hand corner, choose the relevant artifact.
  5. Select the Downloads tab, and scroll down to the “Assets” section.
  6. Click the upload arrow for the mapping file or the debug symbols as applicable to upload the deobfuscation or symbolication file for the version of your app.
Upload files using the Google Play Developer API

To upload files using the Google Play Developer API, go to the Google Developers site.

Step 3: View deobfuscated crash stack traces

After you've uploaded a ProGuard mapping file or debug symbols file for a version of your app, crashes and ANRs that occur afterward will be deobfuscated. You can review deobfuscated stack traces for individual crashes and ANRs on your app's Crashes & ANRs page.

  1. Open the Play Console.
  2. Select an app.
  3. On the left menu, select Quality > Android vitals > Crashes & ANRs.
  4. Select a crash.
  5. In the "Stack Traces" section, you'll see your deobfuscated and symbolicated stack traces.

Important: Once you've uploaded a mapping file for a version of your app, only future crashes and ANRs for that version of your app will be deobfuscated. Crashes and ANRs for a version of your app that happen before you've uploaded its respective mapping file won't be deobfuscated.

Frequently asked questions

I don’t want to use the Play Console deobfuscation / symbolication. Can I just do it offline?

The Play Console uses ndk-stack to symbolize stack traces for native apps, and ReTrace for Java crashes. If you choose not to share your deobfuscation files, you can copy the obfuscated crash stacks from the Play Console and use the appropriate tool offline to symbolicate them. However, this process must be done manually for each crash stack, making it slow and time-consuming. By providing your deobfuscation files, the Play Console will handle this for you.

I’ve uploaded the deobfuscation/symbolication file, so why are my crashes and ANRs still obfuscated?

After you've uploaded a ProGuard mapping file or debug symbols file for a version of your app, only crashes and ANRs that occur afterward will be deobfuscated. You’ll need to allow time for new crashes and ANRs to be reported by users' devices before you see deobfuscated crashes and ANRs in the Play Console.

After uploading the deobfuscation / symbolication file, why are my crashes and ANRs only partially deobfuscated?

This is caused by uploading an incomplete deobfuscation / symbolication file. Make sure you include the symbolication files for your entire app, especially if you use a complex or multi-stage build process. One of the most common reasons for partial deobfuscation is if you use a third-party library. In this case, you may be able to get the deobfuscation files from the library provider.

After uploading the deobfuscation / symbolication file, why do I seem to get fewer, but more severe crashes and ANRs?

Without deobfuscation files, the same crash or ANR on a 32-bit and 64-bit device, or an ARM and an Intel device will be shown separately. By providing deobfuscation files, we can cluster these crashes together, giving you a better perspective of the most impactful crashes and ANRs for your app.

What happens if I forget to upload the file?

If you forget to upload the file for a new version of your app, crashes and ANRs will revert to being obfuscated. Follow instructions above to upload it now. After you've uploaded a ProGuard mapping file or debug symbols file for a version of your app, only crashes and ANRs that occur afterward will be deobfuscated. You’ll need to allow time for new crashes and ANRs to be reported by users’ devices before you see deobfuscated crashes and ANRs in the Console.

To avoid the risk of forgetting to upload the file, consider changing your build process to use app bundles with Android Gradle plugin version 4.1 or later. In this case, you can automatically include the debug symbols file in the app bundle by following the instructions on the Android Developers site.

What happens if I upload the wrong file?

If you upload the wrong file for a version of your app, crashes and ANRs will revert to being obfuscated. To upload a corrected version:

  1. Open the Play Console.
  2. Select an app.
  3. On the left menu, select Release > Devices and versions > App bundle explorer
  4. Using the picker in the top-right-hand corner, choose the relevant artifact.
  5. Select the Downloads tab, and scroll down to the “Assets” section.
  6. Click the delete icon next to the incorrect deobfuscation or symbolication file.
  7. Once the incorrect version is deleted, click the upload icon and upload the correct file for the version of your app.

After you've uploaded the correct ProGuard mapping file or debug symbols file for a version of your app, only crashes and ANRs that occur afterward will be deobfuscated. You’ll need to allow time for new crashes and ANRs to be reported by users’ devices before you see deobfuscated crashes and ANRs in the Console.

Tip: To avoid the risk of uploading an incorrect version of the file, consider changing your build process to use app bundles with Android Gradle plugin version 4.1 or later. In this case, you can automatically include the debug symbols file in the app bundle by following the instructions on the Android Developers site.

I’m currently using APKs. How do I switch to using app bundles?

Visit the Android Developers site to get started.

My app contains both native and Java code. Can I upload both a native symbolication file and a Java deobfuscation file?

Yes.

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue