Lorixen.
EN

Readable Android crash reports after R8 shrinking

Short answer: When you turn on R8 code optimisation for an Android release build, class and method names are shortened, so crash reports show lines like a.b.c(Unknown Source) instead of your real code. Each release build produces a mapping file that translates them back. Keep that file for every version you ship, upload it to Google Play Console and to your crash-reporting tool, automate both steps in your build pipeline, and keep the specific rules you need for code that's accessed by reflection.

Why your crash reports became unreadable

Android's documentation on app optimisation recommends enabling R8 for release builds by setting isMinifyEnabled = true for code optimisation and isShrinkResources = true for resources in the release build type. R8 removes unused code, optimises what's left and renames classes and members to short names. The result is a smaller, faster app, which is exactly what you want to ship.

The side effect is that stack traces from the released app refer to the renamed code. A crash report might read:

java.lang.NullPointerException
    at a.b.c.d(SourceFile:12)
    at a.b.e.f(SourceFile:47)

Without translation, your team can't tell which screen or function crashed, so bugs take far longer to fix, or don't get fixed.

The mapping file is the key

Every time R8 processes a release build, it writes a mapping file that records which original names became which short names. Each build gets its own mapping, because the renaming can differ between builds. Lose the file for a version and crash reports from that version can't be fully decoded later.

Google Play's help pages on deobfuscation describe the solution for Play Console: if you shrink and obfuscate your app, you can upload a mapping file for each version, and Play Console uses it to show readable stack traces for crashes and ANRs in Android vitals. The same page notes that only ReTrace-compatible mapping files are supported, the format ProGuard and R8 produce, and that apps with native code can also upload debug symbol files.

Step 1: archive the mapping for every release

Treat the mapping file as a release artefact, like the app bundle itself:

  • Store it alongside the bundle in your CI system or artefact storage, labelled with the version name and version code.
  • Keep it for as long as that version might still be installed on customers' phones.
  • Never rely on a developer's laptop as the only copy.

Step 2: upload to Play Console

You can upload the mapping manually in Play Console for each app version, but it's easy to forget. Better options:

  • Many CI and deployment tools can upload the mapping file automatically when they publish a release.
  • The Android Gradle plugin includes the mapping in some upload workflows; check your toolchain's documentation.

Check Android vitals after a release: if stack traces still show short names, the mapping didn't arrive.

Step 3: upload to your crash reporter

If you use a separate crash-reporting service, it needs the mapping too. Most provide a Gradle plugin or command-line tool that uploads mappings as part of the release build, matched by version or by a build identifier. Set it up once and confirm with a test crash from a release build.

Step 4: decode stack traces by hand when needed

Sometimes a stack trace arrives another way: a customer email, a log file, a support ticket. Android's tooling includes ReTrace, which takes a mapping file and an obfuscated stack trace and outputs the original names. Android's documentation also notes that tools like Android Studio's Logcat can automatically retrace crashes when the mapping is available. Keep the archived mapping handy so anyone on the team can decode a trace quickly.

Keep rules for reflection and serialisation

Readable crashes are half the job. The other half is making sure R8 doesn't break the app in the first place. Code that's only referenced indirectly, through reflection, JSON serialisation by field name, or some dependency injection setups, can be removed or renamed incorrectly, causing crashes that only appear in release builds.

To avoid that:

  • Use libraries that ship their own keep rules; most popular ones do.
  • Add targeted keep rules for your own classes accessed by reflection, rather than broad rules that disable optimisation for whole packages.
  • Test the release build, not just debug, before every release, including flows that load data from your API.

Native code needs symbols too

If your app includes native code, through a game engine, a media library or your own C++ code, native crashes need debug symbol files to be readable. Play Console accepts these as well, as its help page notes. Make sure your build produces and uploads them.

A release checklist

  1. Release build has R8 enabled with your keep rules.
  2. Mapping file archived with the version name and code.
  3. Mapping uploaded to Play Console.
  4. Mapping uploaded to your crash reporter.
  5. Native symbols uploaded, if relevant.
  6. Release build smoke-tested on a real device.
  7. After rollout, check one crash report is readable.

A worked example

Take a hypothetical Galway veterinary-practice app whose Android release crashed for some clients when opening appointment history. Play Console showed only obfuscated names, and the team had never kept mapping files, so the crash for that version couldn't be decoded. They added mapping archiving and automatic uploads to Play Console and their crash reporter in CI, then shipped a patch release. The next crash report pointed straight to a JSON model class that R8 had renamed; one keep rule fixed it.

FAQ

Should I turn off R8 to avoid the hassle?

No. It makes the app smaller and faster. Handling mapping files is a one-off setup in your build pipeline.

Can I decode crashes from an old version without its mapping?

Only partly, if at all. Each build's mapping is specific to that build.

Do iOS apps have the same issue?

Yes, in a different form: iOS crash reports need dSYM symbol files to be readable.

If your Android crash reports are unreadable, ask us to set up mapping uploads.

Sources

WhatsAppBook a call