Maven Dependency Principles, Conflict Resolution, and Loading Process

Maven Dependency Components

Maven dependencies can be divided into direct dependencies (declared in the project's dependencies section), transitive (indirect) dependencies, dependency management entries, parent direct and indirect dependencies, and BOM (Bill of Materials) dependencies, which include direct, indirect, and managed entries.

Three Core Maven Dependency Principles

1. Shortest‑Path Priority

Maven selects the version reachable via the shortest path in the dependency graph; for example, if a project depends on C‑api‑1.0 (which brings in A‑api‑1.1 ) and also directly on A‑api‑2.1 , the direct path to A‑api‑2.1 is shorter, so that version is used.

2. Declaration‑Order Priority

When multiple versions are reachable, Maven respects the order in which dependencies are declared in the POM; the earlier declaration wins. The article shows how this affects poi‑ooxml vs. poi‑scratchpad when they depend on different versions of poi .

3. Override Priority

Dependencies declared in a child module override those from its parent POM. The example demonstrates a parent POM with A‑api‑1.1 and a child module that adds A‑api‑1.2 , resulting in the child using version 1.2.

Common Maven Dependency Conflict Errors

ClassNotFoundException

Occurs when the required class cannot be found at runtime, often due to missing or mismatched JAR versions.

NoSuchMethodError

Triggered when a method expected at runtime is absent, typically caused by JAR version conflicts where different versions contain incompatible method signatures.

Maven Dependency Loading Process

The loading workflow proceeds as follows:

Insert parent direct, transitive, and managed dependencies before the project's own dependencies.

For each direct dependency, resolve its version (from the declaration or from dependencyManagement) and store it in DependencyMap , overwriting any existing entry with the same groupId:artifactId .

Recursively load each dependency's POM, applying the project's dependencyManagement versions to build a TransitiveDependencyMap .

Add entries from TransitiveDependencyMap that are not already present in DependencyMap .

Repeat steps 3‑4 recursively for any newly discovered transitive dependencies, which explains the shortest‑path principle.

Conclusion

The article summarizes Maven's dependency components, the three governing principles with visual examples, common conflict error types, and the complete loading algorithm, providing a practical guide for developers to diagnose and resolve Maven dependency issues.