Resolving Incompatible Jar Dependency Conflicts with Maven Shade Plugin

The article, authored by the vivo Internet Server Team, addresses the frequent issue of incompatible JAR versions in Java projects, exemplified by a conflict between different versions of Guava required by business code and middleware.

It uses the "wife and mother" metaphor to illustrate the dilemma of choosing which version to keep when both are needed, and describes a typical scenario where Dependency A (business) and Dependency B (middleware) depend on different, conflicting versions of the same library.

Copying the newer library's source code into the project is examined as a possible fix, but the article points out two major drawbacks: extensive transitive dependencies that make the task labor‑intensive, and the maintenance burden of manually updating the copied code when the upstream library changes.

The authors then explore class‑loader isolation approaches. Alibaba’s internal Pandora component and Ant Financial’s open‑source SOFAArk both load different versions of third‑party libraries in separate class loaders, effectively isolating them and eliminating the conflict.

While powerful, such solutions are considered heavyweight for a single project, especially when the organization does not plan to adopt them broadly.

Consequently, the article proposes a lightweight alternative: using the Maven Shade Plugin to relocate (rename) the conflicting packages, allowing both versions to coexist in the same JVM.

The Maven configuration required for this approach is provided below:

4.0.0
com.shaded.example
guava-wrapper
${guava.wrapper.version}
guava-wrapper
https://example.com/guava-wrapper
UTF-8
27.1-jre
1.8
1.8
com.google.guava
guava
27.1-jre
org.apache.maven.plugins
maven-compiler-plugin
3.3
${maven.compiler.source}
${maven.compiler.target}
org.apache.maven.plugins
maven-jar-plugin
2.3.2
default-jar
jar
package
org.apache.maven.plugins
maven-source-plugin
2.4
default-sources
jar-no-fork
org.apache.maven.plugins
maven-shade-plugin
2.4.1
false
com.google.guava
com.google.guava.wrapper
com.google.common
com.google.common.wrapper
com.google.thirdparty
com.google.wrapper.thirdparty
package
shade

After building and publishing the shaded guava-wrapper artifact, the project can simply depend on it:

com.vivo.internet
guava-wrapper
27.1-jre

The conclusion emphasizes that the Maven Shade Plugin offers a lightweight, low‑cost method to make incompatible JARs coexist, suitable for isolated conflicts. For more pervasive dependency‑conflict pain points, heavyweight class‑loader isolation solutions like Pandora or SOFAArk are recommended.