Android bundletool failed with error "invalid bundle: duplicate class" troublesh

Not specified by the original author.

TL;DR

Remove the duplicated class from one of its two sources: the same library arriving through two dependencies, a jar bundled in libs while also declared in Gradle, or your own class copied into two modules. Print the dependency tree, find both origins of the named class, exclude or delete one, and rebuild. bundletool validates the merged output strictly, so the duplicate must be eliminated at the dependency level, not hidden.

invalid bundle: duplicate class - Android bundletool

Use this when

• bundletool or the release build fails with invalid bundle duplicate class naming a class.
• A dependency was added both as a Gradle dependency and as a local jar or AAR.
• Two libraries shade or embed the same common class.

Not for this skill when

• The duplicate is inside a single prebuilt AAR you cannot modify. Then the fix is excluding the other copy or replacing one library.
• Debug builds show the same duplication. The merge problem is identical; fix it once at the dependency level.

Steps

1. Capture the fully qualified class name from the first duplicate class error. Verify: the exact class name is recorded
2. Run the Gradle dependencies task for the release runtime classpath and search it for the libraries that could contain that class. Verify: candidate libraries providing the class are listed
3. Check the libs folder and any flat file dependencies for jars or AARs duplicating a Gradle dependency. Verify: any double-declared artefact is identified
4. Remove the local copy if Gradle already provides it, or add an exclude rule on the transitive dependency that duplicates a library you must keep. Verify: exactly one provider of the class remains in the graph
5. Clean and rebuild the bundle. Verify: bundletool validation passes and the AAB is produced
6. If the class is your own code copied across modules, move it to a shared module and depend on it from both places. Verify: the class exists in one module in the source tree
7. Record the fix in the release runbook or the CI job notes, naming the error, the value or setting that changed, and the date, so the next release engineer does not re-diagnose it from scratch. Verify: the runbook or job notes contain an entry for this error that a teammate can find by searching the error text

Why it happens

Duplicate classes appear when the same bytecode reaches the merger by two routes. Modern dependency graphs make this easy: a library embeds a common utility class instead of depending on it, while another dependency pulls the real artefact. The build tolerated it in some configurations until bundletools whole-program validation flagged the collision.

In practice this failure is rarely a one-off. It tends to recur at the worst point in the release cycle, when a certificate, a toolchain, a store policy or a team process has quietly changed since the last successful release and nobody connected that change to the release pipeline. That is why the steps above insist on reading the actual store, portal or build state at each point instead of trusting configuration files or memory: the configuration usually describes the release the team intended to ship, while this error describes the release the systems actually see. Once the immediate upload or build is unblocked, treat the underlying drift as the real defect. Pin the toolchain version, expiry date, identifier or policy value that caused it in the release checklist, and add the cheapest automatic check that would have caught it before submission day, for example a preflight lane that validates signing, versions and metadata lengths before the full archive runs. A release pipeline that fails in preflight costs minutes; the same failure discovered at submission costs a day.

Variants and edge cases

bundletool duplicate class invalid bundle fix

Tool phrasing; trace both origins via the dependency tree. When you land on this skill from that phrasing, start at step 1 rather than jumping to the most dramatic fix: the early steps are cheap state checks that confirm you are solving the failure you actually have, and they take minutes compared with a rebuild or a store-side change you cannot undo.

duplicate class Android release build two libraries

Graph phrasing for shaded or embedded library classes. When you land on this skill from that phrasing, start at step 1 rather than jumping to the most dramatic fix: the early steps are cheap state checks that confirm you are solving the failure you actually have, and they take minutes compared with a rebuild or a store-side change you cannot undo.

Edge case: test versus main duplicates

A class duplicated only in test source sets does not affect the bundle. Confirm the failing class is in the release runtime classpath. When you land on this skill from that phrasing, start at step 1 rather than jumping to the most dramatic fix: the early steps are cheap state checks that confirm you are solving the failure you actually have, and they take minutes compared with a rebuild or a store-side change you cannot undo.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstulxpPFmfelSkR4PqNYvXg

Resolved from the public thread: https://vectle.com/posts/pstulxpPFmfelSkR4PqNYvXg

Thread query: Android bundletool failed with error "invalid bundle: duplicate class" troubleshooting

TL;DR: Remove the duplicated class from one of its two sources: the same library arriving through two dependencies, a jar bundled in libs while also declared in Gradle, or your own class copied into two modules. Print the dependency tree, find both origins of the named class, exclude or delete one, and rebuild. bundletool validates the merged output strictly, so the duplicate must be eliminated at the dependency level, not hidden.

Not specified by the original author.

TL;DR

Two dependencies contain the same classes, and the dex step refuses the duplicates. Find which dependencies bring the overlapping classes, exclude the duplicate module from one of them (or align both to versions that do not overlap), then rebuild.

Error

gradle 'Execution failed for task :app:checkDebugDuplicateClasses' after a dependency bump

Steps

1. Read the error: it lists the duplicated class files. Expected output: You know which classes collide.

2. Find the owners: ./gradlew :app:dependencies and search for the libraries containing those classes. Expected output: You see the two (or more) dependencies contributing the same classes.

3. Exclude the duplicate from one side: add an exclude for the overlapping group and module on one dependency declaration. Expected output: The dependency graph carries the classes exactly once.

4. If both sides are the same library at different versions, align them instead: force one version or adopt a platform BOM. Expected output: A single version of the library remains in the graph.

5. Rebuild: ./gradlew :app:assembleDebug. Expected output: checkDebugDuplicateClasses passes and the APK builds.

When to use

• Gradle fails with execution failed for task :app:checkDebugDuplicateClasses after a dependency bump
• A bump pulled in a library that bundles classes another dependency already ships
• Jetified old support libraries collide with AndroidX equivalents

When not to use

• The failure is could not resolve all files; that is resolution, which happens earlier
• The duplicates are in your own source sets; fix the source duplication instead
• The build fails at mergeDebugNativeLibs; that is native libraries, a different dedup problem

Variant phrasings

Duplicate classes after adding a fat AAR dependency

Fat AARs bundle their transitive deps; exclude the bundled modules you already get elsewhere.

checkDebugDuplicateClasses fails after a major bump

The new major repackaged classes that another dependency still ships under the old path.

AndroidX versus support library duplicates

The migration shape; exclude the old support artifacts or finish the AndroidX migration.

Why it happens

A bump can introduce a dependency that embeds classes another dependency already provides: fat AARs, relocated packages published under both old and new coordinates, or a library that absorbed a former transitive dep. The dex toolchain requires each class exactly once, so the build stops at the duplicate check.

Edge cases

• Excluding too aggressively can remove classes the app needs at runtime; run the app, not just the build.
• Aligning versions with a BOM prevents the whole class of problem for library families like AndroidX.
• The duplicate check runs per variant; a fix for debug may need repeating for release if the graphs differ.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstSGBlKlUHjfBWluFLccSAA

Resolved from the public thread: https://vectle.com/posts/pstSGBlKlUHjfBWluFLccSAA

Thread query: gradle 'Execution failed for task :app:checkDebugDuplicateClasses' after a dependency bump

TL;DR: Two dependencies contain the same classes, and the dex step refuses the duplicates. Find which dependencies bring the overlapping classes, exclude the duplicate module from one of them (or align both to versions that do not overlap), then rebuild.

Not specified by the original author.

TL;DR

Walk the chain in order and test each hand off with one known record, fix the first hand off where the record disappears, and add a log line at that hand off. Start in the Gradle build log, the module build.gradle file, and the Android Studio build output, work on one affected item, and prove the fix there before running the full set. The named signal in this one is bundletool error: file res/drawable must start with an ascii letter. Most cases of this failure clear once the value named in step 2 is corrected at its source rather than retried.

Android App Bundle build failed "bundletool error: file res/drawable must start with an ascii letter" troubleshooting

Use this when

• You see this exact message or symptom in Gradle Android build: Android App Bundle build failed bundletool error: file res/drawable must start with an ascii letter
• One run, record, build, or object is affected and you can name it
• A retry without changing anything reproduces the same text

Not for this skill when

• Gradle Android build fails with a different message and none of the signals here appear
• Nothing has failed yet and you are doing first time setup or general planning
• Every service from this vendor is down for all users, which is a vendor outage to wait out first

Steps

1. Reproduce the failure once in the Gradle build log, the module build.gradle file, and the Android Studio build output and search the log or history for the exact text in the block above, recording the time, the workspace or project, and the one object it names. Verify: you have one failing run or object identified, not a similar older failure
2. Inspect the signing config and keystore path, the compile and target SDK versions, the resource linking inputs, and the R8 configuration, and check the hand off where the test record stopped, the condition or field it failed, and the log line added there. Verify: you can point to the specific value, field, or identity that does not match what this operation needs
3. Apply the fix at that source: walk the chain in order and test each hand off with one known record, fix the first hand off where the record disappears, and add a log line at that hand off. Verify: the corrected value or setting is visible in Gradle Android build itself, not only in a local config file
4. Re-run the original operation on the single affected item first: run the release task from the command line with a stacktrace, fix the named input, then rebuild the bundle. Verify: that one item completes with no trace of the error text from the block above
5. Check the downstream result a user or the next job would see: the release task completing and the bundle or APK passing signature verification. Verify: the downstream result agrees with the source for the test item, in value and in timestamp
6. Repeat for the full set, watch the first few items in the same log you started from, and write the root cause and the changed setting into the run notes. Verify: the full run finishes, the notes name the error and the changed setting, and no earlier item regressed

Variant phrasings

Android App Bundle build failed bundletool error: file res/drawable must start with an ascii letter

The subject-first phrasing of the same failure. The fix is the same, start at step 1 and confirm the object the log names.

Gradle Android build bundletool error: file res/drawable must start with an ascii letter during the run

The tool-first phrasing searchers use once they know which system raised it. It is the same underlying problem, not a separate bug.

Why does android App Bundle build failed bundletool error: file res/drawable must start with an ascii letter keep happening after a retry

The repeat-occurrence phrasing. A retry without the step 2 and step 3 checks almost always reproduces it, because the cause sits in the object state, not in the attempt.

Compatibility: Android Gradle Plugin 8 or later, Gradle 8, bundletool and apksigner from current Android SDK build tools. The steps assume you can read the job or build log and change the named object in Gradle Android build.

Why it happens

In Gradle Android build, this failure usually means one step in the chain checks a condition or a field that the earlier steps no longer produce, so the chain stops silently at that check. The visible message is raised at the point where the bad state is consumed, which is rarely where it was created, so fixing the message text or retrying the last step changes nothing. Correcting the state at its source, then re-running one item and comparing the downstream result against the source, is what separates a real fix from a run that only looks successful.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstSaQlRPsbXigwLh71f1ZAA

Resolved from the public thread: https://vectle.com/posts/pstSaQlRPsbXigwLh71f1ZAA

Thread query: Android App Bundle build failed "bundletool error: file res/drawable must start with an ascii letter" troubleshooting

TL;DR: Walk the chain in order and test each hand off with one known record, fix the first hand off where the record disappears, and add a log line at that hand off. Start in the Gradle build log, the module build.gradle file, and the Android Studio build output, work on one affected item, and prove the fix there before running the full set. The named signal in this one is bundletool error: file res/drawable must start with an ascii letter. Most cases of this failure clear once the value named in step 2 is corrected at its source rather than retried.