Diagnosing and Resolving Maven Dependency Version Conflicts in Multi‑Module Projects

Problem Statement

When a Maven build fails with a Dependency convergence error or a running application throws ClassNotFoundException, NoSuchMethodError, or LinkageError, the most common culprit is a version conflict on the classpath. In a multi‑module project this can stem from direct, transitive, or profile‑specific dependencies that pull in incompatible artifact versions.

Recognizable Symptoms & Diagnosis Table

Symptom	Likely Cause	Diagnostic Command
Build fails with enforcer:enforce convergence error	Direct + transitive version mismatch	mvn dependency:tree -Dverbose -Dincludes=groupId:artifactId
Runtime NoSuchMethodError	Diamond dependency with incompatible versions	mvn dependency:analyze-duplicate
Different versions packaged in WAR vs EAR	Module‑specific transitive resolution	mvn help:effective-pom -pl <module>
Tests pass but integration tests fail	Test‑scope dependency leaking into compile	mvn dependency:tree -Dscope=test

Ordered Verification Steps

1. Run the enforcer plugin first (if configured) to surface convergence violations:

   mvn validate enforce:enforce

   Requires maven-enforcer-plugin in the parent POM and the enforce goal bound to the validate phase.

2. Map the full dependency graph for the artifact in question:

   mvn dependency:tree -Dverbose -Dincludes=org.example:my-lib

   Use -DoutputFile=tree.txt if the graph exceeds the 1,000‑line default.

3. Detect duplicate classes that could cause runtime clashes:

   mvn dependency:analyze-duplicate

   Inspect the duplicate-classes.txt report for classes found in multiple jars.

4. Inspect effective POMs per module to see if a module overrides a parent dependencyManagement entry or activates a profile that pulls a different version:

   mvn help:effective-pom -pl <module> -DoutputFile=effective-pom.xml

5. Verify the exact artifacts downloaded (snapshot vs release, mirror metadata):

   mvn dependency:resolve -Dclassifier=sources

   Check the local repository path in the output to confirm the version.

Targeted Fixes

• Convergence error – Pin the version in dependencyManagement of the root POM, or exclude the offending version from the transitive dependency:

  <dependencyManagement>
    <dependency>
      <groupId>org.example</groupId>
      <artifactId>my-lib</artifactId>
      <version>1.4.2</version>
    </dependency>
  </dependencyManagement>

• Diamond conflict – Declare the desired version directly in the child module’s dependencies section; Maven’s nearest‑wins rule will then use that version over the transitive one.
• Module divergence – Remove any module‑level overrides that conflict with the parent dependencyManagement and rely on the central version.
• Test‑scope leak – Ensure that test‑only dependencies are declared with <scope>test</scope> and that no transitive dependency pulls them into compile. If necessary, add a <exclusion> to the transitive dependency that brings in the test artifact.

Concrete Example

Suppose module web pulls in commons-lang3:3.9 via spring-core, while module core explicitly depends on commons-lang3:3.12.0. The build reports a convergence error.

mvn validate enforce:enforce
[ERROR] Dependency convergence error:
  commons-lang3:commons-lang3:jar:3.9
  commons-lang3:commons-lang3:jar:3.12.0

Fix: add a dependencyManagement entry in the parent POM and declare commons-lang3 as 3.12.0 there. Then both modules will resolve to the same version, and the enforcer will pass.

Escalation Criteria

• Conflict involves a legacy jar without an Automatic-Module-Name, requiring shading or relocation.
• Pinning a version breaks a downstream consumer; a BOM import is needed instead of direct dependency.
• Resolution depends on a corrupted mirror; run mvn dependency:purge-local-repository and verify with mvn dependency:resolve.
• Cross‑module circular dependency detected; refactor the modules to break the cycle.
• Security CVE mandates a version upgrade that is incompatible with the existing API; coordinate with the team for a migration plan.

Verification Checklist

1. Run mvn validate enforce:enforce – should report no convergence violations.
2. Execute mvn dependency:analyze – should show no undeclared or unused dependencies.
3. Deploy the artifact to a staging repository and import it into a fresh consumer project; run mvn dependency:tree to confirm the transitive version.
4. Run mvn failsafe:integration-test -Pall to ensure all profiles succeed.
5. Inspect the packaged WAR with jar tf target/web.war | grep commons-lang3 – only the pinned version should appear.

Limitations & Practical Checks

• The dependency:tree goal truncates after 1,000 lines; use -DoutputFile for larger projects.
• Exclusions are transitive – excluding a dependency from one parent does not remove it if another dependency pulls it in.
• Snapshot artifacts may resolve to a timestamped file; use -U to force a fresh download.
• Profile‑activated dependencies can silently change resolution; always run diagnostics with -Pall.
• Offline mode (-o) hides resolution failures; run diagnostics online first.

Conclusion

By following the ordered checks, mapping the dependency graph, and applying targeted fixes, most Maven version conflicts in multi‑module projects can be resolved quickly. When the problem persists beyond the escalation thresholds, consider refactoring module boundaries, adopting a Bill‑of‑Materials (BOM), or engaging the wider community for a long‑term solution.