Understanding Maven Dependency Conflicts and Resolution Strategies

Introduction: The article is the 425th original piece, discussing Maven dependency conflicts and how to resolve them.

1.1 What is dependency conflict: In a Maven project, when multiple dependencies introduce different versions of the same library, compilation errors or runtime exceptions may occur.

1.2 Causes of dependency conflict: Many dependencies are declared in the POM; transitive dependencies can bring in different versions of the same artifact, leading to uncertainty about which version Maven will use.

Example: A → C → X(1.0) and B → D → X(2.0) shows two paths to different versions of X.

Maven must choose one version; having both would cause duplicate dependencies.

In most cases Maven automatically selects a version based on its dependency mediation rules.

If the selected version lacks a class or method present in another version, errors such as NoClassDefFoundError, ClassNotFoundException, or NoSuchMethodError arise.

The outcome depends on which version is chosen; sometimes neither works, requiring version upgrades or downgrades of the involved modules.

2. Maven Dependency Principles

2.1 Path‑nearest principle: Within the same POM, for the same JAR with different versions, the version with the shorter dependency path is selected.

Example: X(1.0) path length 3 vs X(2.0) path length 2 → X(2.0) wins.

When path lengths are equal, the declaration‑first principle applies.

2.2 Declaration‑first principle: With equal path lengths, the order of dependency declarations in the POM decides; the earlier declared indirect dependency wins.

Illustrated with A → B → Y(1.0) and C → D → Y(2.0); if A’s declaration precedes C’s, Y(1.0) is used.

Special cases: child POM declarations override parent POM; within the same POM, later declared direct dependencies override earlier ones.

3. How to Exclude Dependencies

3.1 Transitive dependency: Adding a dependency brings in its own dependencies recursively, simplifying management but can cause conflicts.

3.2 Exclusions: Using the <exclusions> tag to actively disconnect a transitive dependency; only groupId and artifactId are needed, no version.

Example exclusion snippet shown.

3.3 Optional dependencies: The <optional> tag hides a dependency from being transmitted; true hides it, false (default) keeps it transitive.

Difference between exclusions and optional: exclusions are set on the dependent that knows the unwanted transitive dependency; optional is set on the dependency itself when you cannot modify the intermediate module.

3.4 Maven aggregation engineering: In multi‑module projects, a parent POM can manage versions via <dependencyManagement> , forcing child modules to use consistent versions and simplifying upgrades.

4. Maven Helper Plugin Analysis

The Maven Helper plugin provides a Dependency Analyzer view that highlights conflicting jars (red) and the currently selected version (white).

Users can right‑click the white area to exclude the unwanted version.

5. Summary

Generally, keeping the higher version is preferred because most JARs are backward‑compatible.

However, if a higher version removes classes or methods used by the project, simply picking the higher or lower version may fail; one may need to upgrade or downgrade the involved modules (e.g., upgrade A so it depends on X(2.0)).

Such changes can affect many places, making POM upgrades in large projects a complex, error‑prone task.