Troubleshooting Maven Dependency Conflicts with dependency:tree
Publication Date:
Updated:
INFORMATION > Troubleshooting Maven Dependency Conflicts with dependency:tree
Bottom line: Run mvn dependency:tree to inspect the resolved graph, then identify which path introduced the unexpected version. Fix the declaration deliberately with an updated direct dependency, dependencyManagement, or a narrowly justified exclusion.
What you'll learn
- How “nearest definition” mediation can hide a requested transitive version.
- How verbose and filtered dependency-tree output narrows a conflict.
- Why deleting local repository files or adding random exclusions is not a durable fix.
Who this is for: Java developers investigating linkage errors, unexpected classes, or vulnerable transitive versions.
2026 context: Plugin options vary by version, so check the current dependency-plugin documentation. Pair graph inspection with an organization-approved software-composition analysis process; a clean tree does not by itself prove a dependency is secure.
Overview
Maven mediates version conflicts while resolving the dependency graph, which can hide a version requested through another path. This article shows how to inspect the result and enforce convergence when the project requires it.
Table of Contents
1. When library conflicts occur in Maven
Maven resolves direct and transitive dependencies, then applies dependency mediation when different paths request different versions of the same artifact. See How Maven resolves transitive dependencies for the underlying repository and POM flow.
A successful build does not prove that every requested version was selected. The resolved graph must be inspected when diagnosing linkage errors, unexpected behavior, or a vulnerable transitive dependency.
2. How to check
Two complementary checks are useful:
- make the build fail when dependency convergence is required;
- inspect the resolved graph with the dependency plugin.
The first check is repeatable in CI. The second is an interactive diagnostic that shows why Maven selected a particular version.
2-1. Enforcing dependency convergence
The Maven Enforcer Plugin provides a dependencyConvergence rule. The historical configuration below demonstrates the rule; use a current supported plugin version rather than copying the old version unchanged.
<project>
...
<build>
<plugins>
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>3.0.0-M3</version>
<executions>
<execution>
<id>enforce</id>
<configuration>
<rules>
<dependencyConvergence/>
</rules>
</configuration>
<goals>
<goal>enforce</goal>
</goals>
</execution>
</executions>
</plugin>
...
</plugins>
</build>
...
</project>
With the rule bound to the build, a non-convergent graph produces an error like the following:
[WARNING]
Dependency convergence error for org.apache.commons:commons-collections4:4.1 paths to dependency are:
+-com.example.todo:todo-web:1.0.0-SNAPSHOT
+-org.apache.poi:poi:3.17
+-org.apache.commons:commons-collections4:4.1
and
+-com.example.todo:todo-web:1.0.0-SNAPSHOT
+-org.apache.commons:commons-collections4:4.0
[WARNING] Rule 0: org.apache.maven.plugins.enforcer.DependencyConvergence failed with message:
Failed while enforcing releasability. See above detailed error message.
Without an enforcement rule, Maven normally mediates the versions and continues. Enable the rule only when convergence is an intentional project policy, because some valid dependency graphs can contain multiple versions through isolated class loaders or plugin realms.
2-2. Inspecting the dependency tree
Display the resolved dependency graph with:
mvn dependency:tree -Dverbose
Depending on the dependency-plugin version, verbose output can label paths that were omitted because another version won mediation. On Windows Command Prompt, the historical example filters those lines with find:
mvn dependency:tree -Dverbose | find "omitted for conflict"
On Unix-like systems, use grep instead, or use the plugin's supported includes and excludes filters. Always inspect the full path that introduced the selected and omitted versions.
3. Conclusion
Use dependency:tree to understand the resolved graph. When a project requires convergence, enforce that policy in the build with a current Maven Enforcer Plugin configuration. Resolve a conflict deliberately through dependency upgrades, dependencyManagement, or a narrowly justified exclusion.
Official references
■INFORMATION
■PROFILE
■CONTACT