Maven Enforcer "Dependency convergence error" - Fix in CI

By Daniel Zoghalchali·Latchkey

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

Diagnose it: resolve the effective POM first

Maven merges parent POMs, profiles, and settings before it builds anything. The configuration causing your failure is frequently inherited or activated by a profile that is on locally and off in CI.

# the fully resolved configuration Maven will actually use
mvn help:effective-pom | head -60

# which profiles are active here vs on your machine?
mvn help:active-profiles

# full error, offline-safe, no colour codes to confuse the log
mvn -B -e -X <goal> 2>&1 | tail -60

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.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation