Introduction

“Unable to merge dex” is an Android build error that appears when Gradle cannot combine compiled bytecode into the final DEX output. The message is broad, so the real cause is usually one of a few concrete issues: duplicate classes, dependency version conflicts, or method-count pressure that requires multidex. The fastest way to fix it is to stop treating it as one error and identify which of those categories you are actually in.

Start by Checking for Duplicate Classes

The most common modern cause is that two dependencies package the same classes. When the Android build tools try to merge them, they fail because the output cannot contain duplicate definitions.

A useful first command is the dependency tree.

./gradlew app:dependencies

That shows which versions of libraries are landing on the classpath. If two artifacts bring in overlapping implementations, you often need to exclude one of them or align versions explicitly.

1dependencies {
2    implementation("com.example:feature-a:1.2.0") {
3        exclude group: "com.google.guava", module: "guava"
4    }
5    implementation("com.google.guava:guava:33.0.0-jre")
6}

The exact library names differ by project, but the pattern is stable: find the duplicate path, then remove or align it.

Method Count Is a Different Problem

Sometimes the error is really about hitting the single-DEX method limit. In that case, the project may need multidex support.

1android {
2    defaultConfig {
3        applicationId "com.example.app"
4        minSdkVersion 21
5        targetSdkVersion 34
6        multiDexEnabled true
7    }
8}
9
10dependencies {
11    implementation "androidx.multidex:multidex:2.0.1"
12}

If your app supports old Android versions and actually needs multidex runtime support, the application class must also be set up correctly.

1import androidx.multidex.MultiDexApplication;
2
3public class MyApp extends MultiDexApplication {
4}

That said, method count is less often the cause than developers assume. Duplicate-class conflicts are usually more common than a raw method overflow in current Android toolchains.

Version Conflicts Often Hide Behind the Same Message

Gradle can resolve two requested versions of a dependency into one selected version, but that does not guarantee all transitive dependencies remain compatible. The build may still fail during dex merging if one part of the graph expects classes that another part shadows or replaces.

A version alignment block can help.

1configurations.all {
2    resolutionStrategy {
3        force "org.jetbrains.kotlin:kotlin-stdlib:2.1.0"
4    }
5}

Use forced versions carefully. They are a debugging tool and sometimes a valid fix, but they can also hide a deeper incompatibility if you apply them blindly.

Clean Old Build Artifacts After Dependency Changes

Stale intermediate outputs can keep the error around after you already fixed the dependency graph. When the dependency set changes, a clean rebuild is worth doing.

./gradlew clean assembleDebug

This does not solve the underlying cause, but it removes noise from cached outputs and helps you confirm whether the dependency change actually worked.

Read the Full Error, Not Just the Headline

“Unable to merge dex” is often only the top line. The useful clue is usually lower in the output, where Gradle names the duplicate class or the conflicting artifact. If you skip that detail, you end up applying random fixes such as enabling multidex when the real issue is a duplicated dependency.

A disciplined workflow is:

1. read the first concrete class or artifact named in the stack,
2. inspect the dependency tree,
3. align, exclude, or update the conflicting libraries,
4. then clean and rebuild.

That is much more reliable than toggling build flags at random.

Common Pitfalls

• Enabling multidex before checking whether the real problem is duplicate classes.
• Leaving multiple versions of the same library in the dependency graph.
• Forcing versions globally without verifying compatibility.
• Ignoring the detailed class name or artifact path shown lower in the Gradle output.
• Assuming a clean build will fix a dependency conflict by itself.

Summary

• “Unable to merge dex” is a symptom, not a root cause.
• The common causes are duplicate classes, dependency conflicts, and sometimes method-count overflow.
• Use ./gradlew app:dependencies to inspect what is actually on the classpath.
• Enable multidex only when you have confirmed the project truly needs it.
• Read the detailed error lines and fix the dependency graph instead of guessing.