Version Conflict & Mediation

## The problem it solves Every build tool that supports transitive dependencies has to solve the same core problem: two different paths through the dependency graph often demand two different versions of the same library, and typically only one version can be placed on the classpath at a time. **Nearest wins** is one of the two classic strategies for picking a winner, and it is the default behavior of Maven and several other tools. ## How the depth rule works Think of your project's dependencies as a tree rooted at your own module. | Depth | What sits there | |---|---| | 1 | what you declare directly in your build file | | 2 | what those direct dependencies declare | | 3 | what depth-2's dependencies declare, and so on | When the resolver walks this tree and finds the same artifact coordinate appearing at multiple depths with different version numbers, it picks the version found at the shallowest depth — the one nearest to your project's own declaration. If two occurrences tie at the same depth, the resolver falls back to a secondary rule, typically **first declared wins**, meaning whichever dependency was listed earlier in your build file takes priority. ## Why it exists The appeal of nearest-wins is that it exists to give the developer direct, predictable control. - **You can override it.** If you don't like what a transitive dependency pulls in, you can override it simply by declaring the version you want directly in your own build file — because your own declaration is always at depth 1, it will always win. - **Easy to reason about.** This makes the rule easy to reason about without needing an explicit force or pin mechanism for the common case. - **Computationally cheap.** It's also a straightforward tree traversal with no need for search or backtracking. ## The trade-off The cost of that simplicity is the trade-off: nearest-wins is purely structural, not semantic. It knows nothing about whether the winning version is actually compatible with what the losing transitive dependency needs. - Depth-1 could specify `libFoo` 1.2, while a critical transitive dependency at depth 4 genuinely requires `libFoo` 2.5's API. Nearest-wins will silently select 1.2, the build will typically still compile and succeed (compile-time resolution only checks that the APIs your own code directly references are present), and the failure only appears later. - Nearest-wins is also sensitive to declaration order and graph shape in ways that are hard for a human to intuit in a large project with hundreds of transitive dependencies — nearest is not the same as safest or newest. ## Failure modes in production The textbook failure mode in production is a runtime error the build did not catch — most commonly `NoSuchMethodError`, `NoSuchFieldError`, or `AbstractMethodError` in JVM ecosystems, thrown when code compiled against a newer API executes against an older jar that nearest-wins put on the classpath instead. This is insidious because CI can be green while a codepath deep in a transitive library still throws at runtime, often only under conditions that exercise the mismatched method. Diagnosing it typically means: 1. dumping the resolved dependency tree; 2. looking for duplicate artifact coordinates with different versions; 3. then tracing which one nearest-wins actually selected. ## Putting it together A concrete scenario: a Spring-based web application directly depends on library A at depth 1, which needs Jackson 2.10. Separately, the application also directly depends on library B at depth 1, which transitively pulls in Jackson 2.15 through an intermediate module at depth 2. If B's code was written expecting Jackson 2.15's newer API, and nearest-wins ends up selecting 2.10 because of how the graph is shaped, requests hitting B's serialization code throw at runtime even though the build was green. The fix in Maven is to explicitly declare the desired Jackson version at depth 1 in the application's own build file, which — because of nearest-wins — forces that version to be selected regardless of what depth it would otherwise have been found at. This is exactly why **just add a direct dependency with the version you want** is the idiomatic way to resolve conflicts in nearest-wins ecosystems.