Confirm that legacy support is needed
This setup concerns applications supporting Android versions below API 21. Modern Android handles multiple DEX files natively. If your minimum SDK is 21 or higher, a multidex-related class name in an old tutorial is not by itself a reason to add the support library. Official multidex guidance.
Choose the least disruptive integration
| Existing application setup | Typical legacy approach |
|---|---|
| No custom Application class | Configure the documented MultiDexApplication class |
| Custom class can extend MultiDexApplication | Preserve your initialization in that subclass |
| Custom class must extend another base | Install multidex in attachBaseContext as documented |
Do not declare two application classes in the manifest. The final merged manifest has one android:name for the application object.
Preserve initialization order
A Kotlin fragment for the third case is:
override fun attachBaseContext(base: Context) {
super.attachBaseContext(base)
MultiDex.install(this)
}
This belongs inside the appropriate Application subclass, with the AndroidX dependency and imports configured. It is not a standalone file. Avoid accessing classes that require secondary DEX loading before the installation point on legacy devices.
Investigate the actual missing class
If startup still fails, record the first missing class, its package and the oldest affected OS version. Check that the final APK contains it and that release shrinking has not removed a reflective entry point. A crash occurring only in a minified release may involve keep rules rather than multidex initialization.
Compare the merged manifest with the source declaration. Build flavors or libraries can alter which application class is used, so editing one source manifest is not proof of the packaged result.
Test the boundary condition
Install the exact release build on a device or emulator representing the minimum supported Android version. Exercise cold start, process recreation and the first feature using secondary-Dex code. A successful modern-device test does not validate the legacy path.
APKLint's DEX / Smali Analyzer can reveal packaged files and structure, but it cannot execute initialization. Keep the local startup test and its logs as the evidence that your chosen integration actually works.
Preserve an existing application class
Suppose the app already has ShopApplication extending a framework-provided base class. Replacing the manifest entry with a generic MultiDexApplication can bypass the app's existing initialization entirely. Follow the documented installation path compatible with that inheritance structure, preserving the superclass call and the framework's required lifecycle contract.
Inspect the final merged manifest for the release variant to confirm which application class Android will construct. A library manifest or flavor-specific declaration can differ from the source file a developer just edited. Also verify that the class is present in the installed package; a correct-looking manifest string cannot instantiate an absent definition.
Find the first access that needs secondary code
The multidex setup documentation places legacy installation in the application startup sequence. Review property initializers, constructors and helper calls reached before that installation. A library referenced too early can fail even though the installation call exists later in the file.
Use a minimal reproduction on the oldest supported runtime: start from a clean installation, launch without a debugger changing timing, and retain the first stack and application lifecycle log. If the failure appears only with release shrinking, compare the packaged class and relevant retention contract before changing initialization order. If it also appears unoptimized on the old runtime, examine loading and primary-DEX requirements.
After the repair, test both a clean first launch and an ordinary later launch. Exercise process recreation and a feature that depends on code outside the initial screen. Confirm that the framework base application's initialization still runs, including any documented dependency setup the product requires. Test a modern device too, but label that as a separate native-multidex path. Remove diagnostic logging that exposes private app state before distribution and keep the lifecycle evidence with the regression. Successful startup should demonstrate that the application's existing responsibilities survived the integration, not merely that a blank activity can open after replacing its Application class.
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
