Maven Dependency Conflict Avoidance Guide

Maven is a widely used build tool for Java projects, but as projects grow the number of dependencies increases, leading to hidden dependency conflicts that can cause runtime errors or build failures.

A dependency conflict occurs when adding a library causes the project to fail to start or produces unexpected errors. The article explains how to detect, visualize, and resolve such conflicts.

Visualizing dependencies – Maven’s mvn dependency:tree command and IDE tools (IntelliJ IDEA, Maven Helper plugin) can display the dependency tree in text or graphical form, highlighting conflicting versions. mvn dependency:tree Example output shows a tree with modules and versions.

Core mechanisms

• Transitivity : A → B → C means A inherits C through B. A -> B -> C • Nearest-wins rule : When multiple versions of the same artifact appear, Maven selects the version from the shortest path in the dependency graph.

A
 ├── B
 │   └── C
 │       └── D 2.0
 └── E
     └── D 1.0   // version 1.0 wins

Explicitly declaring the desired version overrides the rule.

A
 ├── B
 │   └── C
 │       └── D 2.0
 ├── E
 │   └── D 1.0
 └── D 2.0   // forced version

Dependency management – Using dependencyManagement in a parent POM centralizes version declarations, allowing child modules to omit versions.

<properties>
   <fastjson.version>1.2.76</fastjson.version>
</properties>
<dependencyManagement>
   <dependency>
      <groupId>com.alibaba</groupId>
      <artifactId>fastjson</artifactId>
      <version>${fastjson.version}</version>
   </dependency>
</dependencyManagement>

Children then declare only groupId and artifactId.

<dependency>
   <groupId>com.alibaba</groupId>
   <artifactId>fastjson</artifactId>
</dependency>

Scopes – Maven defines six scopes (compile, provided, runtime, test, system, import) that control when a dependency is included.

Exclusions – To remove a transitive dependency, add an <exclusions> block.

<dependency>
   <groupId>com.shizhuang-inc</groupId>
   <artifactId>E</artifactId>
   <exclusions>
      <exclusion>
         <groupId>com.shizhuang-inc</groupId>
         <artifactId>D</artifactId>
      </exclusion>
   </exclusions>
</dependency>

Optional dependencies – Marking a dependency as optional lets the consumer decide whether to include it.

Best practices to avoid conflicts

Identify core modules and focus on their dependencies.

Pay special attention to serialization libraries (Jackson, Gson, Fastjson) and network/RPC libraries (Protobuf, Thrift, Dubbo, gRPC).

Use dependency management and the nearest-wins rule wisely; avoid excluding dependencies unless necessary.

Regularly run mvn dependency:analyze to find unused or undeclared dependencies.

Consider shading (maven-shade-plugin) or flattening plugins to isolate conflicting versions.

By following these guidelines, developers can reduce the risk of runtime failures caused by Maven dependency conflicts.