Guide to Avoiding Maven Dependency Conflicts

Maven is one of the most popular build tools for Java projects, but as the number of dependencies grows, hidden conflicts can threaten runtime stability. A dependency conflict occurs when adding a library causes the project to fail to start or produces unexpected runtime errors.

The article explains how to discover, analyze, and resolve Maven dependency conflicts.

Visualizing dependencies

Use Maven's built‑in command or IDE plugins to display the dependency tree:

mvn dependency:tree

The output shows a hierarchical list of all transitive dependencies. IDEs such as IntelliJ IDEA can render this graphically.

Core mechanisms

Transitivity : If A depends on B and B depends on C, Maven automatically includes C. Example:

A -> B -> C

Nearest‑wins (closest) principle : When multiple versions of the same artifact appear, Maven selects the version that is nearest to the root of the dependency tree. Example:

A
   ├── B
   │   └── C
   │       └── D 2.0
   └── E
       └── D 1.0

Version 1.0 is chosen because the path A→E→D is shorter.

Dependency management : Declare versions in a parent POM using <dependencyManagement> so child modules can omit versions.

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

Scopes (compile, provided, runtime, test, system, import) control when a dependency is included.

Exclusions can remove a transitive dependency that causes conflicts:

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

Optional dependencies are declared with optional=true and are not pulled in transitively unless explicitly added.

Common pitfalls

Multiple declarations of the same dependency with different versions in a single module (the last one wins).

Multiple BOM imports that define different versions of the same artifact; the first BOM wins.

Different modules pulling in conflicting versions of a shared library, leading to runtime AbstractMethodError or class‑loading issues.

Recommendations to avoid conflicts

Identify core modules and focus on their dependency health.

Pay special attention to serialization, network, and RPC libraries (Jackson, Protobuf, Redis clients, etc.).

Declare common dependencies in a parent POM and let child modules inherit versions.

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

Consider using the Maven Helper plugin (install via IDEA) to visualize and resolve conflicts directly in the IDE.

When a dependency must be used by both the library and its consumers, mark it as optional or relocate it with the Maven Shade plugin.

By following these practices, developers can significantly reduce the risk of Maven dependency conflicts and maintain more stable Java services.