Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 41 ยท Dependencies

Diagnosing Dependency Conflicts

Find and fix Maven dependency conflicts with dependency:tree -Dverbose and dependency:analyze, understand NoSuchMethodError and classpath hell, and when to shade.

Few build problems are as confusing as a conflict between two versions of the same library. Everything compiles. The tests may even pass. Then in production a request fails with NoSuchMethodError, a method that you can plainly see in the source of the library. What happened is that the code was compiled against one version and runs against another.

This lesson turns that confusion into a routine. You will learn the symptoms, the two commands that reveal almost everything (dependency:tree and dependency:analyze), the standard fixes, and the last-resort tool, shading. It builds directly on Transitive Dependencies and Mediation and Managing Versions.

Maven cannot run in the browser, so every mvn command and XML snippet below is read-only. The three Java programs are stand-ins: a conflict finder, a simulation of NoSuchMethodError, and a model of dependency:analyze. They show the logic on made-up libraries. They are not the real tools.

Why conflicts hurt

Only one version of a library can be on a classpath. When two of your dependencies were built against different versions of a third library, Maven picks one, and the other dependency is forced to run against a version it was not compiled for. That works if the newer version only adds things. It breaks if the version that wins is older than what some library needs, or if the newer one removed or changed something that another library uses.

This situation has a name: classpath hell, or "JAR hell".

What conflicts look like

NoSuchMethodError A method compiled against is gone at run time.
NoClassDefFoundError A class was there at compile time, not now.
ClassNotFoundException A class is requested by name and cannot be found.
Odd behavior The wrong version quietly does something different.

These errors appear when you run, not when you compile.

1 / 2

The runtime errors have different roots:

  • NoSuchMethodError and NoSuchFieldError: the class exists, but the method or field does not in this version. Classic sign of the wrong version winning.
  • NoClassDefFoundError: a class that was present when the code was compiled is not on the runtime classpath. It can mean a dropped transitive dependency, a wrong scope, or a library that was excluded too eagerly.
  • ClassNotFoundException: code (often a framework using reflection) looked up a class by name and did not find it.
  • AbstractMethodError, IncompatibleClassChangeError: the shape of a class changed between versions.

Step 1: look at the tree

Start with the question "which version of this library is on the classpath, and who asked for the others?"

Terminal
mvn dependency:tree -Dverbose -Dincludes=com.example:x

-Dincludes filters the tree to matching artifacts (groupId:artifactId, wildcards allowed), and -Dverbose keeps the branches that lost the mediation:

TEXT
[INFO] com.example:my-app:jar:1.0
[INFO] +- com.example:lib-a:jar:1.0:compile
[INFO] |  \- com.example:x:jar:1.0:compile
[INFO] \- com.example:lib-b:jar:2.3:compile
[INFO]    \- (com.example:x:jar:2.0:compile - omitted for conflict with 1.0)

Now the problem is visible: lib-a wins at the same depth because it was declared first, so x 1.0 is used, and lib-b, which needs x 2.0, will break wherever it calls something that only exists in 2.0.

The conflict finder below turns a list of requests into that kind of report. It also checks the dangerous case from the lesson on enforcer rules: the chosen version is lower than another request.

Java A conflict finder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Upgrading is usually safer than downgrading, because libraries tend to keep old methods and add new ones. A library that was compiled against x 1.0 normally runs fine on x 1.2. The reverse is the problem. That is exactly what the enforcer rule requireUpperBoundDeps checks.

What a NoSuchMethodError really is

The JVM links method calls by name and signature when the call is first executed. If lib-b was compiled against x 2.0, its bytecode contains a call like x.Parser.parseStrict(String). With x 1.0 on the classpath, the class Parser exists but has no such method, so the call throws.

The next program simulates this with two "versions" of a library described as sets of method names, and one caller compiled against version 2.0.

Java Compiled against 2.0, running on 1.0

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The output shows the asymmetry: the older library keeps working on the newer version, but the newer library breaks on the older one. The real error message is a little different in format (it also includes the full descriptor), but the cause is the same.

Finding the JAR a class came from

When you do not trust what you think is on the classpath, ask the JVM. This one-liner, read-only here, prints the JAR a class was loaded from:

Java
System.out.println(
    com.example.x.Parser.class.getProtectionDomain().getCodeSource().getLocation());

You can also start the program with -Xlog:class+load (Java 9+) to see every class and its source, then search for the class that misbehaves. If the location is not the version you expected, the tree tells you why.

Step 2: analyze what you use

dependency:tree shows what is there. dependency:analyze compares it with what your code uses, by inspecting compiled bytecode:

Terminal
mvn dependency:analyze
TEXT
[WARNING] Used undeclared dependencies found:
[WARNING]    org.slf4j:slf4j-api:jar:2.0.17:compile
[WARNING] Unused declared dependencies found:
[WARNING]    commons-io:commons-io:jar:2.19.0:compile
  • Used undeclared: your code imports a class from a library that you did not declare. It works only because some other dependency brings it in transitively. That is fragile: if that dependency drops it, your build breaks. Declare it yourself.
  • Unused declared: you declared a library that no class of yours references. It may be dead weight to remove, or a false alarm.

False alarms are common for libraries used only through reflection or at run time: a JDBC driver, a logging implementation, annotation processors. Silence them deliberately with ignoredUnusedDeclaredDependencies in the plugin configuration rather than deleting something your app needs. You can also bind the check to the build with dependency:analyze-only and set failOnWarning to true so it becomes a gate.

The model below does the comparison with sets, the same way the report is built.

Java A dependency:analyze model

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Step 3: apply a fix

Once you know the cause, pick the least invasive fix:

  1. Pin the version with dependencyManagement (preferably the highest version that every consumer accepts). This is the cleanest and most common fix.
  2. Upgrade the dependency that pulls in the old library, if a newer release of it exists.
  3. Exclude the unwanted transitive library from one dependency, and make sure the version you want is on the classpath some other way.
  4. Declare a library you use directly instead of relying on a transitive copy.
  5. Shade (below) when two parts of your application truly need different versions at the same time.

After a fix, rerun dependency:tree -Dverbose and confirm the picture changed. Do not trust a fix you have not looked at.

Shading and relocation

Sometimes there is no single version that satisfies everyone. The Maven Shade Plugin can copy a library's classes into your JAR and relocate their packages, so that com.google.common becomes, say, com.example.shaded.guava. The bundled copy no longer clashes with any other copy on the classpath:

XML
<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.6.1</version>
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>shade</goal>
      </goals>
      <configuration>
        <relocations>
          <relocation>
            <pattern>com.google.common</pattern>
            <shadedPattern>com.example.shaded.guava</shadedPattern>
          </relocation>
        </relocations>
      </configuration>
    </execution>
  </executions>
</plugin>

Library authors use this to avoid imposing their dependencies on others. Application developers should reach for it rarely: shaded JARs are larger, harder to debug, and hide the real dependency from tools. Packaging is covered in Packaging: JAR, WAR and Executable Jars.

A checklist

  • Reproduce the error and read the first line of the stack trace. Which class and method?
  • Run dependency:tree -Dverbose -Dincludes=... for the library involved.
  • Decide: pin, upgrade, exclude or declare.
  • Run dependency:analyze for hidden transitive use.
  • Add enforcer rules so the conflict cannot return unnoticed.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. lib-b was compiled against x 2.0, but x 1.0 is on the runtime classpath. What is the most likely failure?

    Code compiled against a newer version calls methods the older version lacks. The JVM only notices when the call is executed.
  2. 2. Which command keeps the branches that lost mediation in its output?

    The verbose flag prints omitted branches such as (x:2.0 - omitted for conflict with 1.0), so you can see who wanted what.
  3. 3. What does 'Used undeclared dependencies' in dependency:analyze mean?

    Your code compiles only because another dependency brings the library in. Declare it explicitly so a change elsewhere cannot break you.
  4. 4. Which fix is usually the cleanest for a version conflict?

    Managed versions also apply to transitive dependencies, so one entry fixes the version for the whole tree. Shading is a last resort.

Summary

  • A conflict means code runs against a different version than it was compiled with. It shows up at run time as NoSuchMethodError, NoClassDefFoundError and similar.
  • Newer versions usually keep older callers working. An older version beating a newer request is the dangerous case.
  • mvn dependency:tree -Dverbose -Dincludes=... shows who requested what, and dependency:analyze reports used-undeclared and unused-declared libraries.
  • Fix by pinning with dependencyManagement, upgrading, excluding or declaring directly. Shade only when two versions must coexist.
  • Re-run the tree after each fix and add enforcer rules to keep conflicts out.

Next: Repositories and the Local Cache