Maven Enforcer "Dependency convergence error" - Fix in CI

The Maven Enforcer dependencyConvergence rule found the same artifact pulled in at two different versions through different dependency paths and failed the build to force you to pick one.

What this error means

The build fails with Dependency convergence error for com.example:lib:1.2 paths to dependency are: ... and ... 1.5, listing the conflicting paths. The enforce goal aborts before compilation.

[ERROR] Rule 0: org.apache.maven.enforcer.rules.dependency.DependencyConvergence
failed with message:
Failed while enforcing releasability.
Dependency convergence error for com.google.guava:guava:31.1-jre paths to
dependency are:
+-com.example:app:1.0.0
  +-lib-a:1.0 -> guava:31.1-jre
  +-lib-b:2.0 -> guava:33.2.1-jre

Common causes

Two transitive paths pull different versions

Two of your dependencies each drag in a different version of a shared library; convergence forbids the split.

No managed version for the shared library

Without a dependencyManagement entry, Maven mediates to nearest-wins, but the enforcer still flags the divergence.

A BOM not imported

A BOM that would align the versions is not imported, so each path keeps its own.

How to fix it

Pin the shared library in dependencyManagement

Declare one version so every path converges on it.

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.guava</groupId>
      <artifactId>guava</artifactId>
      <version>33.2.1-jre</version>
    </dependency>
  </dependencies>
</dependencyManagement>

Exclude the older transitive version

Drop the divergent copy from the dependency that brings the older one.

<dependency>
  <groupId>com.example</groupId>
  <artifactId>lib-a</artifactId>
  <exclusions>
    <exclusion><groupId>com.google.guava</groupId><artifactId>guava</artifactId></exclusion>
  </exclusions>
</dependency>

Import a BOM to align versions

Use a BOM so the whole family converges.

<dependency>
  <groupId>com.google.guava</groupId>
  <artifactId>guava-bom</artifactId>
  <version>33.2.1-jre</version>
  <type>pom</type><scope>import</scope>
</dependency>

How to prevent it

• Manage shared library versions centrally in dependencyManagement.
• Import BOMs to keep dependency families aligned.
• Run mvn dependency:tree -Dverbose to find the diverging paths.

Related guides