All Collections
Advanced usage
Deobfuscating an Android stacktrace
Deobfuscating an Android stacktrace

This article explains how to use a mapping.txt file to deobfuscate the stacktrace of a R8 or Proguard optimized application

Jordi Giménez avatar
Written by Jordi Giménez
Updated over a week ago

When building and optimizing an Android application, R8, and Proguard obfuscate the names of packages, classes, and methods; this makes applications smaller and faster to run but can also be used partly to make the application more difficult to understand to someone using decompilation tools.

This obfuscation is beneficial in most cases but can make it difficult to understand a stack trace appearing in a crash. Fortunately, while obfuscating the application, a mapping file is generated, which can be used to revert the obfuscation.

Manually uploading the mapping file to Bugfender

When you're seeing a crash, you might see a Mapping: missing indication next to the crash. You can use that button to upload your mapping file.

Automatically uploading the mapping file to Bugfender

You can use this Gradle plugin to upload the mapping files automatically when you build your application:

Alternatively, you can write your own script using the /api/upload-symbols endpoint. This can be used, for example, in your CI/CD process before releasing an application.

You can ZIP your mapping file to speed up the upload. This endpoint is available to all users (it does not require a plan with API support). The access token is in the application Settings tab.

Even if the retrace tool is very powerful, depending on the degree of optimization performed it might not be possible to reconstruct the original stacktrace, even with the mapping file.

The following parameters are recommended in your proguard.cfg  file:

-renamesourcefileattribute SourceFile
-keepattributes SourceFile,LineNumberTable

Also, please note that each application version will produce its mapping file, which you must upload to Bugfender separately.


These are the most common reasons why deobfuscation doesn't work:

  • The mapping file must match the application build. If you upload a mapping file from a different version, it will not work.

  • You can only upload one mapping file for a given version. If you upload multiple files, only the last one will be used.

  • If you're debugging a hybrid application, you must upload three files separately: the iOS dSYM files, the Android mapping file, and the Javascript sourcemap files.

Did this answer your question?