Maven Shade "Overlapping classes" / Conflicting Resources in CI

The maven-shade-plugin built an uber-jar and found two (or more) dependencies that contribute the same class or resource path. Shade keeps one and warns about the rest, which can produce a jar that runs the wrong implementation or a broken merged service file.

What this error means

During package, shade prints Overlapping classes: / We have a duplicate ... in ... for specific paths, and the resulting uber-jar may fail at runtime with NoSuchMethodError or a missing SPI provider because the wrong copy won.

[WARNING] guava-32.1.2-jre.jar, listenablefuture-9999.0.jar define 1 overlapping classes:
[WARNING]   - com.google.common.util.concurrent.ListenableFuture
[WARNING] maven-shade-plugin has detected that some class files are
[WARNING] present in two or more JARs.

Common causes

Two dependencies ship the same class

Overlapping or partially-split artifacts (e.g. a full library plus a "stub" jar of one class) both define the same fully-qualified class. Shade can only keep one.

Mergeable resources collide without a transformer

Files like META-INF/services/*, META-INF/spring.handlers, or reference.conf exist in multiple jars. Without a merging transformer, one overwrites the other and breaks service discovery.

How to fix it

Merge service/resource files with transformers

Tell shade to concatenate the collidable resources instead of letting one win.

<configuration>
  <transformers>
    <transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
    <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
      <resource>reference.conf</resource>
    </transformer>
  </transformers>
</configuration>

Relocate or exclude a duplicated class

Relocate a shaded library to its own package, or exclude the redundant stub artifact.

<relocations>
  <relocation>
    <pattern>com.google.common</pattern>
    <shadedPattern>shaded.guava</shadedPattern>
  </relocation>
</relocations>

How to prevent it

• Add ServicesResourceTransformer whenever your dependencies use SPI/service files.
• Relocate bundled third-party packages to avoid classpath collisions in the uber-jar.
• Exclude redundant stub/partial artifacts that duplicate a full dependency.

Related guides