Understand the platform split
Android 5.0 and later provide native support for loading multiple DEX files. Applications that support earlier platform versions need the appropriate AndroidX multidex support path. Your minSdk therefore determines whether legacy initialization is relevant. Android multidex guide.
The limit concerns method references in a DEX file, not the number of source-code methods you personally wrote. Dependencies and their transitive libraries contribute too. DEX structure.
Reduce unnecessary code before adding complexity
Inspect the resolved dependency tree for unused or duplicated libraries. Enable release shrinking where appropriate and avoid broad keep rules that preserve entire SDKs unnecessarily. Multidex makes a large codebase packageable; it does not remove the cost of code that should never have been included.
Check the release variant separately from debug. Test libraries and debugging integrations may distort a debug-only diagnosis.
Configure legacy support only when required
For an application that genuinely supports pre-21 Android, the relevant build setting is:
android {
defaultConfig {
multiDexEnabled = true
}
}
The AndroidX multidex dependency and application initialization must also be configured as documented. This fragment alone is not a complete legacy setup. For minSdk 21 or higher, do not add legacy initialization solely because multiple DEX files appear in the APK.
Inspect the produced files
Use:
apkanalyzer dex list app-release.apk
Expecting only classes.dex after enabling multidex is a mistaken success criterion. The important checks are whether the build succeeds, the required classes are packaged and the app starts correctly on the oldest supported platform.
Diagnose startup failures separately
On legacy platforms, initialization-time classes may need to be available before secondary DEX loading. Reflection and unusual application startup paths can complicate detection. Read the earliest ClassNotFoundException or related stack instead of repeatedly increasing heap settings or deleting caches.
APKLint's DEX analyzer can help inventory the package. It does not run Android's class loader or prove that a legacy startup path works. Test the actual minimum-supported device configuration before shipping a multidex change.
Measure the dependency contribution to a method-reference failure
Consider an application that crosses a DEX reference limit immediately after adding a large SDK. Compare the release dependency graph before and after that addition, including transitives. Determine whether the application needs the full SDK, a smaller supported module, or none of the newly packaged feature. Removing unused functionality is different from simply allowing the same code to span more DEX files.
Read the build diagnostic precisely. The limit is about references representable within a DEX file, so counting only methods written by the application team is misleading. An APK containing several DEX entries is not inherently damaged, and a low count in one debug artifact says little about a different release variant.
Choose a test that crosses the legacy runtime boundary
The official multidex guide separates native support on API 21 and later from the support-library path for older systems. If the product still supports an older minimum API, test that actual release configuration on the old runtime. A development flavor with a higher minimum API can conceal the initialization path that production users need.
Exercise a cold launch and the first feature that loads substantial secondary code. Capture the earliest class-loading failure if startup breaks, then inspect whether the referenced class is packaged and whether it is needed before secondary DEX installation. Keep a main-DEX placement issue separate from a class removed by shrinking; they may both appear as startup failures but have different remedies.
After a dependency cleanup or configuration change, compare the DEX inventory, release size and startup behavior under equivalent conditions. Install the exact candidate rather than assuming a successful incremental deployment has exercised clean installation. Preserve the optimized mapping and configuration because broad keep rules can increase reference pressure as well as package size. If legacy support is no longer a product requirement, changing the minimum API is a separate compatibility decision with user impact. It should not be hidden inside a build-error workaround. The release record should explain both why multiple DEX files are present and why the oldest supported platform can load the required application classes.
Sources and further reading
Reference review: 29 September 2026. Examples illustrate the workflow; check your installed versions, release artifact and account-specific Console requirements before applying them. This guide is not a claim that APKLint executed your project or verified your private account.
Android inspection tools and practical release guides. About APKLint · Report a correction
