Maven Dependency Resolution and Nearest Wins Rule Explained
How Maven picks one version when libraries disagree, why nearest definition wins, how to see the conflicts and pin a version with dependencyManagement.

A method that exists in the library's documentation throws NoSuchMethodError at runtime. The version you declared has it. The version on the classpath does not, because another library in your tree asked for an older version and Maven chose that one. The rule is simple and unintuitive, and it explains many failures that appear on one machine and not another. The related errors are in ClassNotFoundException and NoClassDefFoundError.
The rule
Maven builds the dependency tree and, when the same groupId:artifactId appears more than once with different versions, picks one. This is called mediation. The rules:
- Nearest definition wins. The version declared with the fewest steps from your project is chosen.
- First declaration wins on a tie. If two have the same depth, the one that appears first in your POM wins.
- Your own direct dependency is at depth 1, so your declared version always wins over a transitive one.
An example:
your-app
├── A 1.0
│ └── commons-codec 1.10 (depth 2)
└── B 1.0
└── C 1.0
└── commons-codec 1.16 (depth 3)Maven chooses commons-codec 1.10, because it is closer, though 1.16 is newer. If code in C uses a method added in 1.16, it fails at runtime with NoSuchMethodError. Maven does not choose the highest version, which is the behavior of Gradle's default, and it is a regular source of surprise when moving between the two. The sibling failures are could not resolve dependencies and dependency scopes.
See the conflicts
./mvnw dependency:tree -Dverbose -Dincludes=commons-codecVerbose output marks omitted versions:
[INFO] dev.javahacks:shop:jar:1.0
[INFO] +- com.example:A:jar:1.0:compile
[INFO] | \- commons-codec:commons-codec:jar:1.10:compile
[INFO] \- com.example:B:jar:1.0:compile
[INFO] \- com.example:C:jar:1.0:compile
[INFO] \- (commons-codec:commons-codec:jar:1.16:compile - omitted for conflict with 1.10)The parenthesized line is the loser. Run the command with -Dincludes for the artifact in your error message, or without it to see everything.
Pin the version you want
The dependable fix is dependencyManagement, which sets the version for the artifact everywhere in the tree:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
<version>1.16.1</version>
</dependency>
</dependencies>
</dependencyManagement>Managed versions override transitive requests. Choose a version compatible with every library that uses the artifact; the highest one is usually safe within a major version. Declaring the artifact as a direct dependency also works, at depth 1, though it adds an artifact to your direct list that you do not call. A BOM, as in dependency scopes, applies the same mechanism for a whole family.
Exclude or replace
If a library brings an artifact that you do not want, exclude it:
<dependency>
<groupId>com.example</groupId>
<artifactId>A</artifactId>
<version>1.0</version>
<exclusions>
<exclusion>
<groupId>commons-codec</groupId>
<artifactId>commons-codec</artifactId>
</exclusion>
</exclusions>
</dependency>Exclusions apply only on that path, and exclusions of a library that needs the artifact break it. Use them for duplicates such as old logging bindings.
Make conflicts fail the build
The Enforcer plugin detects them:
<plugin>
<artifactId>maven-enforcer-plugin</artifactId>
<version>3.5.0</version>
<executions>
<execution>
<id>enforce</id>
<goals><goal>enforce</goal></goals>
<configuration>
<rules><dependencyConvergence/></rules>
</configuration>
</execution>
</executions>
</plugin>With dependencyConvergence, any artifact reached by paths with different versions fails the build, which forces a decision. On a large project this produces many errors at first; resolve them once with dependencyManagement and the build stays honest.
Ties go to the first declaration
Nearest wins decides by depth in the tree, and when two paths have the same depth, the dependency declared first in the POM wins. Reordering two dependencies in a POM can therefore change the version on the classpath, with no version number edited. A build that behaves differently after an innocent tidy-up of the dependency list is showing exactly this:
<dependencies>
<dependency><!-- brings guava 31 at depth 2 -->
<groupId>com.example</groupId><artifactId>client-a</artifactId><version>1.0</version>
</dependency>
<dependency><!-- brings guava 33 at depth 2 -->
<groupId>com.example</groupId><artifactId>client-b</artifactId><version>1.0</version>
</dependency>
</dependencies>Here Guava 31 wins, because client-a comes first. The remedy is not to depend on order. Declare Guava directly in your POM at the version you need, so it sits at depth 1 and wins on distance.
Gradle chooses differently
Gradle resolves a conflict by picking the highest version among the candidates, and Maven picks the nearest. A project that migrates from one tool to the other can see a different set of jars with the same declared dependencies. If a class resolves in Gradle and fails in Maven, or the reverse, compare the two resolved trees before debugging the code. Maven's mvn dependency:tree and Gradle's dependencies task print them.
A BOM turns the policy into one place
A bill of materials declares versions for a set of related libraries. Importing it in dependencyManagement makes those versions apply to every module, regardless of depth:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>4.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>Entries in dependencyManagement override transitive versions, which is stronger than nearest wins. With the Boot parent POM or the BOM, a library such as Jackson is the same version in every module, and a transitive request for an older one is ignored. Prefer this over scattering <version> tags through child modules.
Fail the build on divergence
The convergence rule of the Maven Enforcer plugin fails the build whenever two paths want different versions of the same artifact, which makes the silent choices visible:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>3.5.0</version>
<executions>
<execution>
<id>enforce</id>
<goals><goal>enforce</goal></goals>
<configuration>
<rules><dependencyConvergence/></rules>
</configuration>
</execution>
</executions>
</plugin>On a large project the first run produces a long list. Resolve the conflicts that matter by managing the version, and for the others use <exclusions> on the dependency that brings the unwanted one. A rule that is turned on for new modules only is a reasonable compromise on a project that already has hundreds of mismatches.
A reading guide for the tree
| Output | Meaning |
|---|---|
(version managed from 2.1 to 2.3) | A dependencyManagement entry overrode the requested version |
(omitted for duplicate) | The same version was already included higher up |
(omitted for conflict with 1.4) | A different version won the mediation |
(scope managed from compile to runtime) | Management changed the scope |
Use -Dverbose to show the omitted entries, which are the ones that explain a NoSuchMethodError. Search for the artifact with -Dincludes=groupId:artifactId, and the output narrows to the paths that matter.
Recording the decision
A managed version is a decision, and it should say why. When a dependencyManagement entry pins a library below or above what a framework wants, add a comment with the reason and the link to the issue. A year later, someone upgrading the framework sees the pin, reads why it exists and knows whether it can be removed. Without the comment, pins accumulate until nobody dares to touch the section.
Review the managed section at each framework upgrade. Pins that were needed for an older release often have become wrong, and a transitive library held back for one bug fix can leave a newer vulnerability in place.
Where this does not apply
A shaded or fat jar can contain private copies of a library under a different package, which are invisible to mediation. Class loader isolation in application servers gives each application its own copy. Gradle resolves conflicts differently, preferring the highest version. The dependency mediation section of the Maven guide and the Enforcer rules documentation are the primary sources.


