Diagnosing Release-Only Xamarin.Android Crashes After Enabling the Linker

Recognizable condition

Your Xamarin.Android application runs correctly in Debug but crashes in Release after you enable the linker, ProGuard, or R8. The crash log shows Java.Lang.ClassNotFoundException, System.MissingMethodException, or Java.Lang.NoSuchMethodError for types or members that clearly exist in your source code or referenced libraries. The same code path works when AndroidLinkMode is set to None.

Cause and diagnostic table

Observed symptom	Likely cause	What to inspect
Java.Lang.ClassNotFoundException for a type in your app or a binding	Missing Java class, absent native library, or Multi-Dex limit on API 21/22	Whether the Java dependency is present in the APK and whether the device API level is below 23
System.MissingMethodException or Java.Lang.NoSuchMethodError for a C# member	Linker trimmed a member used only by reflection, JNI, or a serializer	Linker warnings and whether the member is referenced directly or only dynamically
Type load or binding mismatch errors after a package update	Mixed Xamarin.Android.Support.* and AndroidX artifacts	NuGet package list for legacy support libraries alongside AndroidX
Crash only on API 21 or 22	Legacy Multi-Dex / dex method-count limit	minSdkVersion and whether Multi-Dex is enabled

Ordered checks

1. Reproduce on the same device and API level in Release. Confirm Debug still works. This isolates the build configuration as the variable.

2. Capture the full crash log. From a terminal with Android SDK platform-tools on PATH, run adb logcat -v threadtime *:E and filter by your package name or PID. Risk: the default buffer may truncate; increase it with adb logcat -G 16M before reproducing.

3. Record the exact build settings. Note AndroidLinkMode, whether ProGuard/R8 is enabled, minSdkVersion, targetSdkVersion, fast deployment, and AOT/LLVM settings. Keep these constant while testing; changing fast deployment or AOT at the same time as the linker makes the result ambiguous.

4. Identify the missing symbol. Determine whether it is a Java binding, a custom Java class, or a C# member accessed by reflection. This tells you which tool removed it.

5. Audit NuGet alignment. List all Xamarin.Android.* and AndroidX packages. Ensure no Xamarin.Android.Support.* packages remain if AndroidX is in use, and that all Xamarin.Android.* versions match.

6. Clean and rebuild. Delete obj and bin directories, then rebuild Release. Stale artifacts can produce misleading linker warnings.

Fixes tied to findings

Trimmed C# reflection member

Add [Preserve(AllMembers = true)] to the affected class, or create a LinkerPleaseInclude file with explicit references. Alternatively, switch AndroidLinkMode to SdkOnly to trim only the Xamarin.Android SDK assemblies rather than your code and third-party libraries.

using Android.Runtime;

[Preserve(AllMembers = true)]
public class UserProfile
{
    public string Name { get; set; }
}

Risk: Preserve attributes increase app size and may hide other trimming issues.

ProGuard/R8 removed a Java class or member

Add keep rules to your ProGuard configuration file. For example, to keep a class used by reflection:

-keep class com.yourcompany.yourlibrary.YourClass { *; }

Risk: Keep rules increase method count; recheck Multi-Dex requirements and APK size.

Missing Java or native library

Verify the binding library or .so files are included in the Release APK and that the architecture (armeabi-v7a, arm64-v8a, x86, x86_64) matches the device.

Crash only on API 21/22

Enable Multi-Dex. In the .csproj, set:

<AndroidEnableMultiDex>true</AndroidEnableMultiDex>

Or enable it in project properties. This addresses the legacy dex limit for minSdk below 21.

Mixed support and AndroidX packages

Remove all Xamarin.Android.Support.* packages and migrate fully to AndroidX. Align all Xamarin.Android.* package versions before adjusting linker settings.

Escalation criteria

Escalate to the library maintainer or Xamarin.Android support when:

• Release still fails with AndroidLinkMode disabled and ProGuard/R8 turned off, proving the issue is not trimming.
• A missing symbol originates from a Xamarin.Android or AndroidX binding assembly after you have aligned package versions and applied keep rules.
• A clean checkout on a supported toolchain reproduces the crash and blocks release.

When escalating, include a minimal reproduction project, the full adb logcat output, linker warnings, the complete NuGet package list, the device API level and architecture, and a description of Debug-versus-Release behavior.

Limitations and verification

Linker defaults, R8 behavior, minSdk rules, and AndroidX migration requirements vary across Xamarin.Android, .NET, and Android SDK versions. Confirm the behavior against your installed toolchain before changing release settings. Fast deployment and AOT/LLVM options also differ between Debug and Release; keep them constant while isolating the linker.

To verify a fix:

1. Build Release with AndroidLinkMode set to None. If the crash disappears, the trimming path is implicated.
2. Re-enable the linker with warnings enabled and inspect the build output for the missing type or member. Apply the preserve or keep rule, rebuild, and confirm the original stack trace no longer appears.
3. Use Android SDK build tools such as apkanalyzer to compare the Debug and Release APKs for the missing class or method.
4. Run the minimal reproduction on an emulator or physical device at the reported API level and architecture after a clean obj/bin rebuild.