Versions and the BOM

Release Trains

Spring Cloud is many projects released together as a release train, named by year: 2023.0.x, 2024.0.x, 2025.0.x. Each train works with a specific Spring Boot line. Mixing the wrong versions gives startup errors such as "Spring Boot [3.x] is not compatible with this Spring Cloud release train".

Spring Cloud release train	Codename	Spring Boot
2022.0.x	Kilburn	3.0.x, 3.1.x
2023.0.x	Leyton	3.2.x, 3.3.x
2024.0.x	Moorgate	3.4.x
2025.0.x	Northfields	3.5.x
2025.1.x	Oakwood	4.0.x

Tip: Always check the compatibility table on spring.io/projects/spring-cloud before upgrading, or let Spring Initializr pick the version for you.

Adding Spring Cloud to a Service (the BOM)

You import the Bill of Materials (BOM) once in dependencyManagement. Then every Spring Cloud starter is added without a version, and the BOM keeps them compatible:

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.4.5</version>
</parent>

<properties>
    <java.version>21</java.version>
    <spring-cloud.version>2024.0.1</spring-cloud.version>
</properties>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <!-- no <version>: the BOM decides -->
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.cloud</groupId>
        <artifactId>spring-cloud-starter-openfeign</artifactId>
    </dependency>
</dependencies>

Gradle Version

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.4.5'
    id 'io.spring.dependency-management' version '1.1.7'
}

ext {
    set('springCloudVersion', '2024.0.1')
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.cloud:spring-cloud-starter-netflix-eureka-client'
}

dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
    }
}

Example

Check which versions Maven resolved:

./mvnw dependency:tree -Dincludes=org.springframework.cloud

Example output

[INFO] com.shopease:order-service:jar:1.0.0
[INFO] +- org.springframework.cloud:spring-cloud-starter-netflix-eureka-client:jar:4.2.1:compile
[INFO] |  +- org.springframework.cloud:spring-cloud-starter:jar:4.2.1:compile
[INFO] |  +- org.springframework.cloud:spring-cloud-netflix-eureka-client:jar:4.2.1:compile
[INFO] \- org.springframework.cloud:spring-cloud-starter-openfeign:jar:4.2.1:compile

Note: The train is called 2024.0.1, but the individual projects inside it have their own numbers (Spring Cloud Commons/Netflix/OpenFeign 4.2.x). That is normal.

Practice

Exercise: Your team is on Spring Boot 3.3.6 and someone adds spring-cloud-dependencies version 2025.0.0. The app fails at startup. Why, and what are the two possible fixes?

Show answer

Release train 2025.0.x (Northfields) is built for Spring Boot 3.5.x.
Its compatibility check fails on Boot 3.3.

Fix 1: use the matching train for your Boot version:
       <spring-cloud.version>2023.0.5</spring-cloud.version>   (Boot 3.2/3.3)
Fix 2: upgrade Spring Boot to 3.5.x and keep 2025.0.x.

(Turning the check off with spring.cloud.compatibility-verifier.enabled=false
 only hides the problem; do not do it.)