Spring Boot Dependency Convergence: BOM, Starters & Version Override Rules
This article explains how Spring Boot achieves dependency version convergence through BOM (spring-boot-dependencies), details starter aggregation mechanics, and outlines four version override methods with priority rules, Maven arbitration behavior, conflict troubleshooting via dependency:tree, and risks of overriding tested version combinations.
Why Version Convergence Is Needed
1.1 Sources of Dependency Conflicts
A Spring Boot application indirectly pulls in dozens of libraries: Spring Framework, logging, JSON, database drivers, connection pools, validation, etc. Each library brings its own transitive dependencies. When versions are not unified, the following problems arise:
The same library is pulled in multiple versions; only one ends up in the final artifact.
API incompatibilities between versions cause runtime errors such as NoSuchMethodError and ClassNotFoundException even though compilation succeeds.
Auto-configuration is designed against a specific version; swapping versions leads to inconsistent behavior.
1.2 Cost of Manual Version Maintenance
If every dependency declares its own version:
Upgrading Spring Boot requires changing dozens of version numbers individually.
Easy to miss some, leaving conflicting versions behind.
No guarantee that the chosen combination has been compatibility-tested.
1.3 Convergence Goals
Version convergence aims to:
Manage a tested set of component versions in a single central file.
Allow business dependencies to be declared without versions.
Enable global adjustments by changing one place.
Make conflicts observable and excludable.
Spring Boot achieves this via a BOM (Bill of Materials) .
BOM Dependency Management
2.1 What Is dependencyManagement
Maven's dependencyManagement only declares versions and configuration without actually pulling in dependencies; real inclusion still happens in dependencies.
<dependencyManagement>
<dependencies>
<!-- versions defined here, not downloaded -->
</dependencies>
</dependencyManagement>
<dependencies>
<!-- actual inclusion, versions managed above -->
</dependencies>2.2 spring-boot-dependencies Structure
Spring Boot's BOM is spring-boot-dependencies. Internally it:
Uses a set of properties to define each component's version number.
References those properties in dependencyManagement for each dependency.
<properties>
<jackson-bom.version>2.17.2</jackson-bom.version>
<hikari.version>5.1.0</hikari.version>
<logback.version>1.5.6</logback.version>
</properties>
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.fasterxml.jackson</groupId>
<artifactId>jackson-bom</artifactId>
<version>${jackson-bom.version}</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>${hikari.version}</version>
</dependency>
</dependencies>
</dependencyManagement>2.3 Two Ways to Import
Method 1: Inherit Parent POM (via spring-boot-starter-parent which itself inherits dependencies)
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.3.0</version>
</parent>Method 2: Import BOM (when you already have a parent POM)
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>3.3.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>Both approaches make dependencies in dependencies automatically receive BOM-managed versions.
2.4 Gradle Equivalent
Gradle imports the BOM via a platform:
dependencies {
implementation platform('org.springframework.boot:spring-boot-dependencies:3.3.0')
implementation 'org.springframework.boot:spring-boot-starter-web'
}Spring's Dependency Management Plugin can also apply version rules uniformly.
2.5 What the BOM Manages
Spring Framework, logging implementations, JSON, validation, connection pools, database drivers, and other common components.
Version combinations are validated by Spring Boot at release time.
Third-party libraries not covered by the BOM still require explicit version declarations.
Starter Essence: Dependency Aggregation & Transitive Inclusion
3.1 Starters Contain No Business Code
A starter is essentially an aggregation POM that declares a cohesive set of dependencies without any compiled code. Adding a starter pulls in all its declared transitive dependencies at once.
For example, spring-boot-starter-web aggregates:
spring-boot-starter-web
├── spring-boot-starter (base + logging + auto-configuration)
├── spring-boot-starter-json (Jackson etc.)
├── spring-boot-starter-tomcat (embedded container)
├── spring-web
└── spring-webmvc3.2 Official vs. Third-Party vs. Custom Starters
Official starters : spring-boot-starter-*, targeting common capabilities (web, data-jpa, security, validation, redis, etc.).
Third-party starters : Community or internal packages bundling a set of components with auto-configuration.
Custom starters : Write your own auto-configuration classes plus an aggregation POM for other modules to consume.
3.3 Transitive Dependency Resolution
Project → starter → library → deeper libraries form a dependency tree. Maven resolves compatible versions along each path; libraries not managed by the BOM follow arbitration rules.
3.4 Overlap Between Starters
Multiple starters often bring in the same components (e.g., Jackson, logging). The final version is determined by version convergence and arbitration rules, not by declaration order.
Version Override Methods & Priority Rules
4.1 Method 1: Explicit Version on Dependency
Declare a version directly in dependencies to override the BOM:
<dependency>
<groupId>com.zaxxer</groupId>
<artifactId>HikariCP</artifactId>
<version>5.1.0</version>
</dependency>A directly declared version takes precedence over transitive resolution.
4.2 Method 2: Override in dependencyManagement
Lock versions centrally in your project's dependencyManagement without changing inclusion:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.17.2</version>
</dependency>
</dependencies>
</dependencyManagement>This only pins versions, suitable for unified overrides.
4.3 Method 3: Override BOM Properties
BOM versions come from properties; override them in your project with the same property names:
<properties>
<jackson-bom.version>2.17.2</jackson-bom.version>
</properties>All components referencing that property shift together, ideal for whole-family upgrades.
4.4 Method 4: Exclude Transitive Dependencies
Remove unwanted transitive artifacts via <exclusions>:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
</exclusion>
</exclusions>
</dependency>Commonly used to swap embedded containers or eliminate conflicting logging implementations.
4.5 Priority Rules (High to Low)
1. Version declared directly in project dependencies
2. Version locked in project dependencyManagement
3. Version provided by BOM / parent POM dependencyManagement
4. Transitive dependency arbitration result (nearest path wins)4.6 Maven Arbitration Rules (When Unlocked)
When the same component appears with multiple versions and no dependencyManagement locks it:
Nearest path wins : the version with the shortest dependency tree path is chosen.
If path lengths are equal, the first declared wins.
4.7 Risks of Overriding
Spring Boot's auto-configuration is tested against BOM versions. Arbitrary overrides may cause:
API incompatibilities leading to runtime errors.
Auto-configuration detection failures.
Version mismatches between interdependent components.
Before overriding, verify the upgrade/downgrade scope and run integration tests.
Conflict Troubleshooting
5.1 Inspect the Dependency Tree
Maven's most direct diagnostic tool: mvn dependency:tree Common filters:
# Show who pulls in a specific component
mvn dependency:tree -Dincludes=com.fasterxml.jackson.core:jackson-databind
# Show duplicate/conflicting versions with verbose paths
mvn dependency:tree -DverboseThe output reveals every version's introduction path, pinpointing "who brought in the old version".
5.2 Common Conflict Symptoms
NoSuchMethodError : Compile-time vs. runtime version mismatch; method removed/renamed in newer version.
ClassNotFoundException : Required class not pulled in or excluded.
NoClassDefFoundError : Dependency initialization failure or version mismatch.
Duplicate log output : Bridge/implementation conflicts, multiple logging bindings active.
5.3 Troubleshooting Steps
Run dependency:tree to list all versions and introduction paths for the conflicting component.
Determine whether the BOM manages that component and why its version changed.
If a fixed version is needed, lock it in dependencyManagement.
Exclude unwanted transitive dependencies via exclusion.
Rebuild and verify the actual runtime version loaded.
5.4 Multiple BOM Imports
Projects may import Spring BOM, third-party BOMs, etc. When multiple BOMs appear in dependencyManagement, the one declared first takes precedence ; conflicting components use the version from the earliest BOM.
5.5 Custom Starter Code Perspective
A minimal custom starter structure:
my-spring-boot-starter/
├── pom.xml # aggregation dependencies
└── src/main/java/
└── com.demo.autoconfigure/
├── MyProperties.java
├── MyAutoConfiguration.java
└── META-INF/spring/... # auto-configuration registrationThe starter declares dependencies; the auto-configuration class handles runtime wiring. Both work together.
BOM dependency management, starter aggregation, and version arbitration are core Java engineering topics and frequent interview subjects for mid-to-senior roles. Mastering convergence and override rules enables you to reason about Maven/Gradle builds, auto-configuration, component upgrades, and conflict diagnosis — precisely locating issues like "version mismatch", "method not found", or "stale dependencies".
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
