Classpath Conflict: Duplicate Classes

Why This Happens

When the same class exists in multiple JARs, the JVM may load different versions from different classloaders. This causes LinkageError when these versions interact. Maven/Gradle dependency conflicts are the most common cause.

The Problem

<!-- Two JARs both contain com.google.common.collect.ImmutableList -->
<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>31.0</version>
</dependency>
<!-- Another dependency that shades an old Guava version -->

The Fix

<!-- Exclude the duplicate -->
<dependency>
    <groupId>com.other</groupId>
    <artifactId>library</artifactId>
    <exclusions>
        <exclusion>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
        </exclusion>
    </exclusions>
</dependency>

Step-by-Step Fix

1. 1

   Identify the conflicting class

   Read the error message for the class name. Use mvn dependency:tree to find which JARs provide it.

2. 2

   Find the duplicate sources

   Search for the class in all JARs using jar -tf or a classpath analysis tool.

3. 3

   Exclude the duplicate

   Use Maven exclusions or Gradle exclude to remove the unwanted version from your dependency tree.