Maven Shade "overlapping classes" warning promoted to error - Fix in CI
The Shade plugin merged your dependencies into one uber jar and found the same class in two artifacts. When you configure it to fail on overlap, the warning becomes a build-breaking error.
What this error means
The shade goal logs We have a duplicate <class> in <jar-a> and <jar-b> or overlapping classes, and the build fails because <failOnError> / an enforcer-style check is set, or a relocation collision was detected.
[WARNING] lib-a-1.0.jar, lib-b-2.0.jar define 14 overlapping classes:
[WARNING] - org.example.util.Strings
[WARNING] ...
[ERROR] Failed to execute goal
org.apache.maven.plugins:maven-shade-plugin:3.6.0:shade (default):
overlapping classes detected; failing buildCommon causes
Two dependencies bundle the same package
A library and a "fat" or relocated variant of the same code both ship org.example.*, so the shaded jar would contain duplicates.
A transitive duplicate of a common util
Shared utility packages (commons-logging, slf4j shims) appear in more than one transitive path.
Conflicting relocations
Two relocation rules map different inputs onto the same target package, colliding after the move.
How to fix it
Exclude the duplicate from one artifact
Drop the redundant copy so only one provider of the class remains.
<dependency>
<groupId>com.example</groupId>
<artifactId>lib-b</artifactId>
<exclusions>
<exclusion><groupId>org.example</groupId><artifactId>util</artifactId></exclusion>
</exclusions>
</dependency>Relocate one package to avoid the clash
Move one provider into a shaded namespace so the classes no longer overlap.
<relocations>
<relocation>
<pattern>org.example.util</pattern>
<shadedPattern>app.shaded.example.util</shadedPattern>
</relocation>
</relocations>Merge service files with the right transformer
For SPI/META-INF overlaps, append rather than overwrite using the services transformer.
<transformers>
<transformer implementation=
"org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
</transformers>How to prevent it
- Run
mvn dependency:treeto spot duplicate providers before shading. - Relocate bundled libraries into a private namespace in fat jars.
- Keep one source of truth for shared utility packages.