Introduction

Yes, there is an official compatibility matrix. Spring Cloud publishes a release train that maps to specific Spring Boot versions, and using mismatched versions is one of the most common sources of cryptic build failures in Spring microservices. This article provides the current matrix, shows you how to check compatibility programmatically, and walks through how to configure your project correctly.

The Official Compatibility Matrix

The canonical source is the Spring Cloud project page, which publishes this mapping. Here is the current matrix:

Starting with the 2020.0.x release, Spring Cloud switched from London-borough code names (Hoxton, Greenwich) to a calendar-based versioning scheme (YYYY.MINOR.PATCH).

How to Check Compatibility Programmatically

Using start.spring.io API

The Spring Initializr API exposes compatible version combinations:

# Get all available Spring Cloud versions for Spring Boot 3.4.x
curl -s https://start.spring.io/actuator/info | python3 -m json.tool

Using the Spring Cloud BOM

The most reliable way to ensure compatibility is to import the Spring Cloud BOM (Bill of Materials) in your build configuration. The BOM manages all Spring Cloud dependency versions for you.

Configuring Your Project

Maven (pom.xml)

1<parent>
2    <groupId>org.springframework.boot</groupId>
3    <artifactId>spring-boot-starter-parent</artifactId>
4    <version>3.4.1</version>
5    <relativePath/>
6</parent>
7
8<properties>
9    <java.version>21</java.version>
10    <spring-cloud.version>2024.0.0</spring-cloud.version>
11</properties>
12
13<dependencyManagement>
14    <dependencies>
15        <dependency>
16            <groupId>org.springframework.cloud</groupId>
17            <artifactId>spring-cloud-dependencies</artifactId>
18            <version>${spring-cloud.version}</version>
19            <type>pom</type>
20            <scope>import</scope>
21        </dependency>
22    </dependencies>
23</dependencyManagement>
24
25<dependencies>
26    <dependency>
27        <groupId>org.springframework.cloud</groupId>
28        <artifactId>spring-cloud-starter-config</artifactId>
29        <!-- version managed by BOM - do NOT specify -->
30    </dependency>
31    <dependency>
32        <groupId>org.springframework.cloud</groupId>
33        <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
34    </dependency>
35</dependencies>

Gradle (build.gradle)

1plugins {
2    id 'java'
3    id 'org.springframework.boot' version '3.4.1'
4    id 'io.spring.dependency-management' version '1.1.7'
5}
6
7ext {
8    set('springCloudVersion', '2024.0.0')
9}
10
11dependencies {
12    implementation 'org.springframework.cloud:spring-cloud-starter-config'
13    implementation 'org.springframework.cloud:spring-cloud-starter-netflix-eureka-client'
14    implementation 'org.springframework.cloud:spring-cloud-starter-gateway'
15}
16
17dependencyManagement {
18    imports {
19        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
20    }
21}

Gradle Kotlin DSL (build.gradle.kts)

1extra["springCloudVersion"] = "2024.0.0"
2
3dependencies {
4    implementation("org.springframework.cloud:spring-cloud-starter-config")
5    implementation("org.springframework.cloud:spring-cloud-starter-gateway")
6}
7
8dependencyManagement {
9    imports {
10        mavenBom("org.springframework.cloud:spring-cloud-dependencies:${property("springCloudVersion")}")
11    }
12}

What Happens When Versions Are Mismatched

Using incompatible versions leads to failures that can be hard to diagnose. Here are the most common symptoms:

Real example: Boot 3.4 with Cloud 2022.0

1***************************
2APPLICATION FAILED TO START
3***************************
4
5Description:
6An attempt was made to call a method that does not exist.
7The attempt was made from the following location:
8    org.springframework.cloud.commons.util.InetUtils.<init>
9
10The following method did not exist:
11    org.springframework.boot.autoconfigure.web.ServerProperties.getAddress()

This happens because Spring Cloud 2022.0 was compiled against Spring Boot 3.0/3.1 APIs, and ServerProperties changed in Boot 3.4. The fix: upgrade to Spring Cloud 2024.0.x.

Upgrading Spring Cloud: Step-by-Step

When upgrading Spring Boot and need to align Spring Cloud:

Step 1: Check the matrix

Identify which Spring Cloud release train matches your target Boot version from the table above.

Step 2: Update the BOM version

1<!-- Before -->
2<spring-cloud.version>2023.0.0</spring-cloud.version>
3
4<!-- After -->
5<spring-cloud.version>2024.0.0</spring-cloud.version>

Step 3: Check for deprecated modules

Some Spring Cloud modules have been removed or replaced across versions:

Step 4: Run tests and check for deprecation warnings

1# Maven
2mvn clean test -Dmaven.compiler.showDeprecation=true
3
4# Gradle
5./gradlew test --warning-mode all

Step 5: Check the release notes

Always read the Spring Cloud release notes for breaking changes:

https://github.com/spring-cloud/spring-cloud-release/wiki/Spring-Cloud-<VERSION>-Release-Notes

Key Spring Cloud Components and Their Boot Requirements

Common Pitfalls

• Hardcoding individual Spring Cloud dependency versions. Always use the BOM to manage versions. If you set <version> on individual Spring Cloud dependencies, you risk version conflicts between Cloud modules that were designed to work together.
• Mixing Spring Cloud modules from different release trains. All Spring Cloud dependencies in a project must come from the same release train. Mixing spring-cloud-config from 2023.0.x with spring-cloud-gateway from 2024.0.x will cause class-loading issues.
• Forgetting that Spring Cloud bootstrap is no longer automatic. Since Spring Cloud 2020.0, the bootstrap context (bootstrap.yml) requires an explicit dependency: spring-cloud-starter-bootstrap. Without it, your bootstrap.yml is silently ignored.
• Not checking Spring Boot patch version compatibility. While the matrix shows major/minor ranges (e.g., 3.4.x), early patch versions of Spring Boot can occasionally have issues. Use at least the second or third patch release for production.
• Assuming start.spring.io always uses the latest compatible combination. The initializer defaults to the latest stable versions, but it may lag behind the very latest patch releases.

Summary

• The official Spring Cloud compatibility matrix is maintained at spring.io/projects/spring-cloud and maps release trains to Spring Boot versions.
• Always use the Spring Cloud BOM (spring-cloud-dependencies) to manage versions. Never hardcode individual dependency versions.
• The current recommended combination for new projects is Spring Cloud 2024.0.x with Spring Boot 3.4.x.
• When upgrading, check for removed modules (Hystrix, Zuul, Ribbon, Sleuth) and their replacements.
• Mismatched versions typically manifest as NoSuchMethodError, BeanCreationException, or ClassNotFoundException at startup.
• Read the release notes for each Spring Cloud release train before upgrading, especially when crossing major Boot version boundaries (2.x to 3.x).