Dependency convergence error
ID: java/maven-dependency-conflict
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 3 | active | — | — | — |
Root Cause
Maven dependency convergence errors occur when different transitive dependency paths resolve to different versions of the same artifact. Maven's nearest-definition-wins strategy silently picks one version, which can cause runtime NoSuchMethodError or ClassNotFoundException.
genericWorkarounds
-
88% success Use <dependencyManagement> to pin conflicting dependency versions and enforce convergence with maven-enforcer-plugin
1. Run 'mvn dependency:tree' to visualize the full dependency tree and identify version conflicts. 2. Add maven-enforcer-plugin with <DependencyConvergence/> rule to make conflicts a build failure. 3. For each conflict, add the desired version to <dependencyManagement> in the parent POM. 4. Test thoroughly — check that all libraries work with the chosen version. 5. Use 'mvn dependency:analyze' to find unused or undeclared dependencies.
-
85% success Use a BOM (Bill of Materials) to manage consistent dependency versions across the project
1. Import a BOM in <dependencyManagement> with scope 'import' and type 'pom'. 2. Common BOMs: spring-boot-dependencies, jackson-bom, aws-sdk-bom. 3. BOMs ensure all related artifacts use compatible versions. 4. When using multiple BOMs, import order matters — later BOMs override earlier ones. 5. For custom projects, create your own BOM POM that centralizes version declarations.
Dead Ends
Common approaches that don't work:
-
Excluding all transitive dependencies and manually declaring every dependency
70% fail
Excluding all transitives and re-declaring them is an enormous maintenance burden. You lose automatic transitive resolution — the main benefit of a dependency manager. New versions of direct dependencies may add new transitive requirements that you will miss, causing ClassNotFoundException at runtime.
-
Always picking the latest version of conflicting dependencies without testing compatibility
55% fail
The latest version may have breaking API changes that other dependencies are not compatible with. For example, library A might require Guava 30.x and be incompatible with Guava 33.x. Blindly upgrading can introduce NoSuchMethodError, ClassNotFoundException, or behavioral changes.