Android DEX Bytecode and MultiDex: The Full Loading Pipeline

After an old project upgraded to AGP 7.0 last year, CI suddenly failed with this error:

Cannot fit requested classes in a single dex file (# methods: 72136 > 65536)

A newer teammate’s first reaction was to add multiDexEnabled true. After that, the app showed a blank screen for 3 seconds during startup. This was not just a configuration problem. It came from not understanding the DEX format and the ClassLoader pipeline.

Hard limits in the DEX file structure

DEX is the bytecode format executed directly by the Android runtime, ART or Dalvik. Its structure consists of a header and several data sections. The core fields are defined in dex_file.h:

Header (112 bytes)
|-- magic[8]       // "dex\n035\0"
|-- checksum       // adler32
|-- signature[20]  // SHA1
|-- file_size / header_size / endian_tag
|-- link_size / link_offset
|-- map_offset
|-- string_ids_size / string_ids_off
|-- type_ids_size / type_ids_off
|-- proto_ids_size / proto_ids_off
|-- field_ids_size / field_ids_off
|-- method_ids_size / method_ids_off  <-- key field
|-- class_defs_size / class_defs_off
`-- data_size / data_off

method_ids_size is a uint32, so in theory it can hold 2 to the 32nd method references. But the real bottleneck is not here.

The real problem is the index width of method_id references. When a DEX instruction invokes a method, the method index is encoded as a 16-bit field. For example, invoke-virtual {v0, v1}, method@BBBB uses BBBB, which occupies 2 bytes and is capped at 65,536 values.

This limit is not determined by the header. It is determined by the encoding space of the bytecode instruction set. To keep each invoke instruction compact, Google compressed method, field, and type indexes into 16-bit fields. That was plenty in 2010, but a mid-sized app today can easily exceed 100,000 methods.

Splitting: from classes.dex to classesN.dex

The core MultiDex logic lives in AGP’s D8MainDexListTask. The build flow has three steps:

1. Collect entry classes: D8 or R8 scans the Manifest, subclasses of android.app.Application, and classes loaded reflectively from attachBaseContext, then marks them as main-dex candidates.
2. Trace direct references: starting from those entry classes, it recursively traces all directly referenced classes, including superclasses, interfaces, and annotations, and writes them to mainDexList.txt.
3. Split dex files: remaining classes are sorted by class name, and every group of roughly 65,536 method references goes into a classesN.dex.

You can manually influence mainDexList.txt to ensure critical classes land in the main dex:

# mainDexList.txt
com/example/MyApplication.class
com/example/CriticalService.class

Before AGP 3.0, multiDexKeepFile and multiDexKeepProguard were essentially ways to manipulate this file. In the D8 and R8 era, declaring --main-dex-list rules through ProGuard configuration is cleaner.

ClassLoader loading pipeline

Android’s class-loading hierarchy looks like this:

BootClassLoader
  `-- PathClassLoader or DexClassLoader
        |-- DexPathList
        |     |-- DexFile (classes.dex)
        |     |-- DexFile (classes2.dex)
        |     `-- DexFile (classesN.dex)
        `-- ClassLoader parent

When PathClassLoader is created, it loads only classes.dex. The key code is in DexPathList.makeDexElements():

// Simplified Dalvik/ART source code.
Element[] elements = new Element[dexFiles.size()];
for (int i = 0; i < dexFiles.size(); i++) {
    elements[i] = new Element(dexFiles.get(i), ...);
}

The secondary classesN.dex files are not loaded automatically. This is why using the MultiDex library directly in Application.onCreate() can crash: at that point, classes2.dex has not yet been attached to the ClassLoader.

The androidx.multidex library mounts secondary dex files during attachBaseContext:

@Override
protected void attachBaseContext(Context base) {
    super.attachBaseContext(base);
    MultiDex.install(this);
}

Internally, MultiDex.install() does three things:

1. Extract the APK and collect all classesN.dex files.
2. Reflectively call DexPathList.makeDexElements() to create an Element array.
3. Merge the old and new Element arrays and write the result back to DexPathList.

// Core merge logic.
Object[] newElements = (Object[]) makeDexElements.invoke(
    pathList, extractedFiles, optimizedDir, null, loader);
Object[] oldElements = getDexElements(pathList);
Object[] allElements = new Object[oldElements.length + newElements.length];
System.arraycopy(oldElements, 0, allElements, 0, oldElements.length);
System.arraycopy(newElements, 0, allElements, oldElements.length, newElements.length);
setDexElements(pathList, allElements);

One detail is easy to miss: when Element arrays are merged, secondary dex elements are appended to the end. ClassLoader searches classes from front to back, so classes in classes.dex have the highest priority. If the same class appears in both the main dex and a secondary dex, only the main-dex version is loaded.

Three production pitfalls

Reflection in Application. If Application.onCreate() uses Class.forName() to load a class outside the main dex, that line can execute before MultiDex.install(), throwing ClassNotFoundException. Move this logic into attachBaseContext after MultiDex.install().

Instant Run and Apply Changes interference. Android Studio’s Apply Changes can replace Elements inside DexPathList during incremental updates. In some AGP versions, MultiDex Element merge order can be disrupted. If startup crashes during debugging, run Build > Clean Project and do a full build first to rule out tooling interference.

Dex loading timing in multi-process apps. If the same Application is reused across multiple processes, such as android:process=":remote", MultiDex.install() runs in every process startup. For lightweight processes that do not depend on non-main-dex classes, such as a Push Service, skipping MultiDex initialization can save startup cost:

@Override
protected void attachBaseContext(Context base) {
    super.attachBaseContext(base);
    String process = getProcessName();
    if (!":push".equals(process)) {
        MultiDex.install(this);
    }
}

Performance tradeoffs

The cost of MultiDex installation is concentrated in two phases: I/O extraction and reflective Element merging. On low-end devices, MultiDex.install() can take 1 to 3 seconds. Several optimizations help:

• Trim the main dex: reduce direct dependencies from entry classes so more classes fall into secondary dex files. This usually has little effect on startup because class loading is lazy.
• Dex compilation cache: Android 5.0+ ART supports AOT. On first run, classesN.dex is compiled to cached OAT files, so later startups can bypass dex2oat work.
• App Bundles: distribute dex by device architecture through Play, indirectly reducing method count.

The worst issue I hit on Android 4.x devices was an ANR during MultiDex.install(). The cause was secondary-dex extraction running synchronously on the main thread inside attachBaseContext. On low-end devices it took more than 2 seconds, freezing the main thread and showing an ANR dialog. If your Application initialization is already heavy, show a loading state immediately after MultiDex.install() so users do not feel the app is stuck. Avoiding the ANR dialog is the baseline; there is still room to improve perceived experience.

multiDexEnabled true is only the starting point. You need to understand the root of the DEX format limit, the ClassLoader mounting time, and Element merge priority to avoid turning one compile error into a production crash. At the instruction-set level, the number 65,536 was never designed to make room for today’s method counts.