Version conflicts: nearest wins
Two dependencies can bring two versions of the same artifact. Maven does not fail on that: it picks one version, drops the other, and builds. The rule it uses is called nearest wins, and it is a rule about the shape of the graph, not about which version is newer or better. This article builds a project where the rule picks the wrong one, and the failure it produces does not look like a version problem at all.
The project
The aggregate dependency at 5.14.3, and one of its modules declared again at 5.11.0. Both versions are in the local repository of this image, so everything below resolves offline.
pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>conflict</artifactId>
<version>1.0.0</version>
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.release>21</maven.compiler.release>
</properties>
<dependencies>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter</artifactId>
<version>5.14.3</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.junit.jupiter</groupId>
<artifactId>junit-jupiter-api</artifactId>
<version>5.11.0</version>
<scope>test</scope>
</dependency>
</dependencies>
</project>
src/main/java/com/example/conflict/Calc.java
package com.example.conflict;
public class Calc {
public static int add(int a, int b) {
return a + b;
}
}
src/test/java/com/example/conflict/CalcTest.java
package com.example.conflict;
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.junit.jupiter.api.Test;
class CalcTest {
@Test
void addsTwoNumbers() {
assertEquals(4, Calc.add(1, 3));
}
}
The tree
The tree of this project is shorter than the one of the previous article, which is the first sign that something was dropped:
mvn -B dependency:tree
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------< com.example:conflict >------------------------
[INFO] Building conflict 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- dependency:3.7.0:tree (default-cli) @ conflict ---
[INFO] com.example:conflict:jar:1.0.0
[INFO] +- org.junit.jupiter:junit-jupiter:jar:5.14.3:test
[INFO] | +- org.junit.jupiter:junit-jupiter-params:jar:5.14.3:test
[INFO] | \- org.junit.jupiter:junit-jupiter-engine:jar:5.14.3:test
[INFO] | \- org.junit.platform:junit-platform-engine:jar:1.14.3:test
[INFO] \- org.junit.jupiter:junit-jupiter-api:jar:5.11.0:test
[INFO] +- org.opentest4j:opentest4j:jar:1.3.0:test
[INFO] +- org.junit.platform:junit-platform-commons:jar:1.11.0:test
[INFO] \- org.apiguardian:apiguardian-api:jar:1.1.2:test
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
junit-jupiter-api is at 5.11.0 and junit-platform-commons at 1.11.0, while the engine is still at 5.14.3 and its platform engine at 1.14.3. The API module of 5.14.3 is nowhere in the list, although the aggregate of 5.14.3 declares it. The tree does not say it was dropped; it only says what is left.
The lines that were dropped
-Dverbose prints the dropped lines too, in brackets, with the reason:
mvn -B dependency:tree -Dverbose
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------< com.example:conflict >------------------------
[INFO] Building conflict 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- dependency:3.7.0:tree (default-cli) @ conflict ---
[INFO] com.example:conflict:jar:1.0.0
[INFO] +- org.junit.jupiter:junit-jupiter:jar:5.14.3:test
[INFO] | +- (org.junit.jupiter:junit-jupiter-api:jar:5.14.3:test - omitted for conflict with 5.11.0)
[INFO] | +- org.junit.jupiter:junit-jupiter-params:jar:5.14.3:test
[INFO] | | +- (org.junit.jupiter:junit-jupiter-api:jar:5.14.3:test - omitted for conflict with 5.11.0)
[INFO] | | \- (org.apiguardian:apiguardian-api:jar:1.1.2:test - omitted for duplicate)
[INFO] | \- org.junit.jupiter:junit-jupiter-engine:jar:5.14.3:test
[INFO] | +- org.junit.platform:junit-platform-engine:jar:1.14.3:test
[INFO] | | +- (org.opentest4j:opentest4j:jar:1.3.0:test - omitted for duplicate)
[INFO] | | +- (org.junit.platform:junit-platform-commons:jar:1.14.3:test - omitted for conflict with 1.11.0)
[INFO] | | \- (org.apiguardian:apiguardian-api:jar:1.1.2:test - omitted for duplicate)
[INFO] | +- (org.junit.jupiter:junit-jupiter-api:jar:5.14.3:test - omitted for conflict with 5.11.0)
[INFO] | \- (org.apiguardian:apiguardian-api:jar:1.1.2:test - omitted for duplicate)
[INFO] \- org.junit.jupiter:junit-jupiter-api:jar:5.11.0:test (scope not updated to test)
[INFO] +- org.opentest4j:opentest4j:jar:1.3.0:test
[INFO] +- org.junit.platform:junit-platform-commons:jar:1.11.0:test
[INFO] | \- (org.apiguardian:apiguardian-api:jar:1.1.2:test - omitted for duplicate)
[INFO] \- org.apiguardian:apiguardian-api:jar:1.1.2:test
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
Read the reasons. omitted for conflict with 5.11.0 appears four times: the API module of 5.14.3 was reached twice (through the aggregate and through the engine) and dropped twice, in favour of the 5.11.0 this pom declares. omitted for conflict with 1.11.0 is the same story one level down: the platform commons of 1.14.3 lost to the 1.11.0 that the API of 5.11.0 brings. omitted for duplicate is harmless: the same artifact at the same version reached by another path, kept once.
(scope not updated to test) on the API line is not a problem either: it says the scope of the direct declaration was already test and stayed test.
Nearest wins
Maven builds the graph as a tree of paths from the project to each artifact. When an artifact appears on two paths, the one with the fewest steps wins, and when two paths have the same length, the declaration that comes first in the pom wins. Here the API of 5.11.0 is one step from the project (declared directly) and the API of 5.14.3 is three steps away (project, aggregate, api), so the nearer one wins.
Three consequences follow, and each one surprises somebody:
- A direct declaration is the strongest thing a pom can do, even when the version it names is older than the one everything else expects.
- The rule is about distance, not about versions: an older version can win, and a newer one can win, and neither is checked for compatibility with the rest of the graph.
- Nothing warns. The build that follows either works, or fails somewhere that has nothing to do with the pom line that caused it.
The run that fails
The test class is ordinary and the compiler accepts it: the API of 5.11.0 has @Test and assertEquals as well. The run is where the mixed graph shows:
mvn -B test > build.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" build.log
status: 1
[INFO] Scanning for projects...
[INFO]
[INFO] ------------------------< com.example:conflict >------------------------
[INFO] Building conflict 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO] -------------------------------------------------------
[INFO] T E S T S
[INFO] -------------------------------------------------------
[ERROR] TestEngine with ID 'junit-jupiter' failed to discover tests
[INFO]
[INFO] Results:
[INFO]
[INFO] Tests run: 0, Failures: 0, Errors: 0, Skipped: 0
[INFO]
[ERROR] at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:103)
[ERROR] at java.base/java.lang.reflect.Method.invoke(Method.java:580)
[ERROR] at org.codehaus.plexus.classworlds.launcher.Launcher.launchEnhanced(Launcher.java:255)
[ERROR] at org.codehaus.plexus.classworlds.launcher.Launcher.launch(Launcher.java:201)
[ERROR] at org.codehaus.plexus.classworlds.launcher.Launcher.mainWithExitCode(Launcher.java:362)
[ERROR] at org.codehaus.plexus.classworlds.launcher.Launcher.main(Launcher.java:314)
[ERROR] -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException
TestEngine with ID 'junit-jupiter' failed to discover tests with Tests run: 0: the engine of 5.14.3 was compiled against the platform of 1.14.3 and calls methods the API of 5.11.0 does not have, so it fails before it can list a single test. The stack trace under the message is all Maven and surefire: the exception the engine threw is swallowed by the forked process, and the only line that names the cause is the one above.
Why this happened
The two versions do not belong to the same release. JUnit 5 numbers its platform and its jupiter modules separately but ships them together: jupiter 5.14.3 goes with platform 1.14.3, jupiter 5.11.0 with platform 1.11.0. A graph with the API of one release and the engine of another mixes two of them, and nothing in a pom says that these artifacts must move together.
Four ways out, in the order a project usually tries them:
- Remove the direct declaration, if it was there for no reason. Then the aggregate's version wins for the whole graph, because it is the nearest one.
- Raise the direct declaration to the version the rest of the graph expects. That works and keeps the line, but the next upgrade of the aggregate leaves the line behind again.
- Put the version in dependencyManagement, which beats the nearest-wins rule for every path: the next article does that with the JUnit BOM and makes this project green.
- Exclude the module from the dependency that brings the wrong version, which is the section on exclusions of the same article.
The local repository is the other half of the story: both versions had to be there for the build to get this far. A version that is in no repository stops the build at the resolution step with a message of its own, which is the failure the errors article reproduces.
Where to go next
dependencyManagement and BOMs takes this project, imports the JUnit BOM and turns the red run green without touching the two dependencies. The local repository article opens the folder both versions of the API came from.
Article author: Arthur Isaev