Preventing Version Drift in Multi-Module Maven Projects

Two modules in the same repository pull different versions of the same library. One compiles against version 2.15, while another transitively brings in 2.13. The build passes and tests pass, but production throws a NoSuchMethodError because the runtime classpath contains the older version. The solution is not more discipline in every POM file; it is the <dependencyManagement> block in a parent POM.

The <dependencyManagement> section acts as a centralized version catalog. It allows a parent POM to define the version, scope, and exclusions for a dependency without actually adding that library to the classpath of every child module. A child module must still explicitly declare the dependency in its own <dependencies> section, but it can omit the version tag, inheriting the managed version from the parent.

How Dependency Management Controls the Graph

In Maven, a transitive dependency is a library required by one of your direct dependencies. Maven resolves these using a "nearest-definition" strategy. Without central management, different modules in a large project can easily drift, pulling in conflicting versions of the same utility library via different transitive paths.

By placing a dependency in the <dependencyManagement> block of a parent POM, you create a rule that overrides the nearest-definition logic. Whenever that specific groupId and artifactId appear in the dependency tree—whether as a direct declaration in a child or a transitive dependency from a third-party library—Maven will use the version specified in the management block.

Key Behaviors

• Non-Intrusive: Defining a library here does not add the JAR to the classpath. Children only get the library if they explicitly declare it.
• Inherited: Management rules flow down the hierarchy. A grandchild module inherits the versions defined in the grandparent's management block.
• Overridable: A child module can still specify its own version tag to override the parent, though this is generally discouraged as it reintroduces version drift.

Practical Implementation: Parent as Version Catalog

To implement this, define a property for the version in the parent POM and reference that property within the <dependencyManagement> block. This makes security patches a single-line change.

<!-- Parent POM -->
<project>
  <groupId>com.example</groupId>
  <artifactId>platform-parent</artifactId>
  <version>1.0.0</version>
  <packaging>pom</packaging>

  <properties>
    <jackson.version>2.17.0</jackson.version>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>${jackson.version}</version>
      </dependency>
    </dependencies>
  </dependencyManagement>
</project>

The child module then declares the dependency without a version:

<!-- Child POM -->
<project>
  <parent>
    <groupId>com.example</groupId>
    <artifactId>platform-parent</artifactId>
    <version>1.0.0</version>
  </parent>
  <artifactId>service-a</artifactId>

  <dependencies>
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <!-- Version is inherited from parent management -->
    </dependency>
  </dependencies>
</project>

Importing External BOMs

A Bill of Materials (BOM) is a POM file that only contains a <dependencyManagement> section. Large frameworks like Spring Boot provide BOMs so you don't have to manually track compatible versions of dozens of interconnected libraries.

You import a BOM using the import scope within your own <dependencyManagement> block:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-dependencies</artifactId>
      <version>3.2.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Verification and Diagnostics

To verify that the managed version is being applied correctly, run the following command from the child module's directory:

mvn dependency:tree

Requirements: This requires read access to the POM files and a configured local Maven repository. No elevated permissions are needed.
Expected Result: The output should show the version defined in the parent POM for the specified artifact, even if a transitive dependency requested a different version. If you update the version in the parent and re-run the command, the child's tree should update automatically.

Limitations and Trade-offs

The primary risk is "hidden" configuration. In deeply nested parent-child hierarchies, it can become difficult to determine which parent is actually managing a version. If a child module overrides a managed version, it silently breaks the consistency the system was designed to provide.

To diagnose these issues, use mvn help:effective-pom. This command outputs the final, merged POM that Maven actually uses for the build, revealing exactly which version was selected and from where it was inherited. To minimize confusion, keep your parent-child hierarchy shallow and document critical version properties clearly.