java classpath_error ai_generated true

java.lang.LinkageError: loader constraint violation: duplicate class definition

ID: java/jar-hell

Also available as: JSON · Markdown
78%Fix Rate
84%Confidence
60Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
17 active — — —

Root Cause

Multiple JARs on the classpath contain the same class, causing the classloader to encounter conflicting definitions. Common with shaded/fat JARs, duplicate transitive dependencies, or libraries that repackage common utilities.

generic

Workarounds

  1. 85% success Use Maven Enforcer's banDuplicateClasses rule or Gradle's duplicate class detection to identify and resolve conflicts 
    1. Add the Maven Enforcer Plugin with the extra-enforcer-rules banDuplicateClasses rule. 2. Run 'mvn enforcer:enforce' to get a report of duplicate classes and which JARs contain them. 3. Exclude the redundant transitive dependency from the dependency that pulls it in. 4. If both JARs are needed, use Maven Shade Plugin's relocation feature to relocate one copy's package.
  2. 82% success Exclude conflicting transitive dependencies and pin a single version 
    1. Run 'mvn dependency:tree -Dverbose' to see all transitive dependencies and conflicts. 2. Identify which dependency pulls in the duplicate JAR. 3. Add an <exclusion> for the duplicate in pom.xml. 4. Explicitly declare the version you want in the <dependencyManagement> section. 5. Verify with 'mvn dependency:tree' that only one version remains.

Dead Ends

Common approaches that don't work:

  1. Randomly removing JARs from the classpath until the error disappears 75% fail

    Without understanding which classes conflict and which version each part of the application needs, randomly removing JARs will likely cause ClassNotFoundException or NoClassDefFoundError instead.

  2. Using a custom classloader to isolate each JAR 70% fail

    Custom classloaders add significant complexity and can cause ClassCastException when the same class loaded by different classloaders is treated as different types. This approach is only viable for plugin systems, not general dependency resolution.

Error Chain

Leads to:
Preceded by:
Frequently confused with: