It Only Crashes in Release — Tracking Down When R8 Full Mode Broke My Gson Mapping

Deobfuscate with mapping.txt and retrace

Every time R8 obfuscates, it emits mapping.txt, a table that maps the original names to the shortened ones. Without it, an obfuscated stack trace is unreadable.

app/build/outputs/mapping/release/mapping.txt

This file changes with every build, so you must keep the mapping.txt for the build you shipped (upload it to Crashlytics or the Play Console and it will restore obfuscated reports automatically). To deobfuscate a local logcat, use retrace, which ships with AGP.

# Save the crash portion of logcat to crash.txt, then restore the original names
retrace app/build/outputs/mapping/release/mapping.txt crash.txt

After restoring, a line that read a.b.c.d turns back into something like com.example.wallpaper.data.CategoryRepository.load. Only then does it click: "Oh, this is where I parse the category-config JSON." A view that was invisible while you stared at the obfuscated form suddenly opens up.

If you hand the restored stack trace and the before/after mapping to an agent-style IDE like Antigravity, it will quickly suggest a hypothesis such as "this class is deserialized by Gson, and once its fields are obfuscated the mapping breaks unless there's a @SerializedName." That said, which keep rule you ultimately adopt is a trade-off between app size and safety that you have to own yourself, so I find it safest to treat the agent's suggestion as a starting point rather than the answer.

What to keep — four options

Once you know the cause is "the fields Gson reads got obfuscated," there's more than one fix. Here are the four I reach for most, with their side effects.

Where I ultimately landed was a combination: decouple field names from JSON keys with @SerializedName, then protect the data-class members with -keepclassmembers. I'll go into the why in the next section, but in one line: "keep obfuscation on, and pin only the names Gson depends on" gave the best balance of size and safety.

Pin the keys with @SerializedName, protect with minimal keep

First, rewrite the model so it no longer depends on field names. With @SerializedName, even if the field is obfuscated to a, Gson always looks at the key named in the annotation.

import com.google.gson.annotations.SerializedName
 
data class Category(
    // Even if the field name is obfuscated, the JSON key stays "display_name"
    @SerializedName("display_name") val displayName: String,
    @SerializedName("wallpaper_count") val wallpaperCount: Int,
    @SerializedName("is_premium") val isPremium: Boolean = false,
)

But @SerializedName alone can be insufficient. R8 full mode may delete a field it judges unused, or remove the no-arg constructor that Gson invokes via Unsafe. So we keep the model's members and constructor.

# proguard-rules.pro
 
# Preserve data-class members (prevent field removal/renaming)
-keepclassmembers class com.example.wallpaper.data.** {
    <fields>;
    <init>(...);
}
 
# Models using generics (List<Category> etc.) need type information too
-keepattributes Signature
 
# Preserve annotations Gson references internally
-keepattributes *Annotation*

-keepattributes Signature is unglamorous but important. When you deserialize a generic type like List<Category>, if R8 drops the type signature, Gson can't resolve the element type and it degrades into a generic type such as LinkedTreeMap, throwing ClassCastException. @SerializedName does not fix this, which makes it an easy second-stage trap to miss.

The reason for keeping <init>(...) is that full mode sometimes treats the data class's no-arg constructor as unused and strips it. Gson calls that constructor via reflection, so once it's gone, you crash at the instance-creation stage.

Verify the fix on a release build

After adding the keep rules, build release again with the fix and walk through the reproduction steps on your own machine. "The build passed" is not "it's fixed." With obfuscation-related bugs, my honest experience is that you can't call it fixed until you actually open the screen in the obfuscated binary.

./gradlew clean assembleRelease
adb install -r app/build/outputs/apk/release/app-release.apk
# Open the screen that was crashing; visually confirm JSON-derived values (category names, etc.) render correctly

It's also reassuring to check the mapping.txt diff. If the fields you wanted to protect stay under their original names while everything else is properly obfuscated, that's evidence your keep scope isn't too broad.

# Did the protected field survive under its original name? (= keep is working)
grep "displayName" app/build/outputs/mapping/release/mapping.txt

For my wallpaper app, I rolled the fixed version out via staged release starting at 5%, confirmed that the crash in question produced zero events on the new build in Crashlytics, then widened to 100%. With release-only bugs, not trusting a debug-build "it works" too much turns out to be the shortest path in the end.

For a wider look at release-specific crashes, the coreLibraryDesugaring blind spot that crashes only on older Android devices and automating obfuscated-report analysis with Firebase Crashlytics belong to the same "only shows up in production" family and should help.

Operational notes so it doesn't recur

Three operational habits to avoid falling in the same hole twice. First, make it a rule to add @SerializedName to JSON-mapped models from the start. Obfuscation-caused bugs are expensive to reproduce after the fact, so preventing them at write time is the cheapest option. Second, always keep the mapping.txt for the build you shipped, and upload it to Crashlytics and the Play Console — without it, production crash reports arrive obfuscated and unreadable. Third, bake a check into CI or your release procedure: "at minimum, open the key JSON-reading screens once on a release build."

R8 full mode is an excellent system that, left alone, quietly makes your app smaller and faster. But the parts that rely on reflection break silently unless you state your intent. Rather than capping it all with "keep everything," draw the line once in your own app to protect only the single broken spot — and the next release gets a lot easier.