java classpath_error ai_generated true

java.lang.LinkageError: loader constraint violation

ID: java/linkage-error

Also available as: JSON · Markdown
76%Fix Rate
83%Confidence
50Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
17 active — — —

Root Cause

LinkageError indicates an incompatibility between classes that were compiled together but have changed incompatibly at runtime. Commonly caused by classloader conflicts in application servers, OSGi containers, or complex multi-module builds.

generic

Workarounds

  1. 82% success Identify the conflicting class versions using -verbose:class and align dependencies 
    1. Run with -verbose:class to log which JAR each class is loaded from. 2. Search the output for the class mentioned in the LinkageError. 3. If it is loaded from an unexpected JAR, you have a classpath conflict. 4. Use 'mvn dependency:tree' to find which dependencies pull in the conflicting JAR. 5. Exclude the unwanted version and pin the correct one in dependencyManagement.
  2. 78% success In application servers, configure class loading to parent-last to prefer app classes over server-provided classes 
    1. In Tomcat: ensure conflicting libraries are not in both WEB-INF/lib and tomcat/lib. 2. In WildFly/JBoss: use jboss-deployment-structure.xml to exclude server modules. 3. In WebSphere: set classloader policy to PARENT_LAST. 4. In general, avoid bundling libraries that the application server already provides (e.g., servlet-api, JPA).

Dead Ends

Common approaches that don't work:

  1. Catching LinkageError and retrying the class load 95% fail

    LinkageError is a fatal error indicating a structural incompatibility between class files. Retrying will load the same incompatible classes and produce the same error. The classpath must be corrected.

  2. Deleting all class files and rebuilding without checking dependency versions 65% fail

    A clean rebuild only helps if your own source code caused the incompatibility. Most LinkageErrors come from conflicting third-party library versions on the classpath, which persist after rebuilding.

Error Chain

Leads to:
Preceded by:
Frequently confused with: