Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Spring Boot refuses to start: wrong Spring Cloud release train

ErrorAPPLICATION FAILED TO START

Short answer

Spring Cloud checks the Spring Boot version on the classpath at startup and stops the app when the pairing is wrong. Pick the release train from Spring's compatibility table for your Boot generation, or move Boot to a generation your train supports.

  • Applies to Spring Boot 3.x, Spring Cloud 2023.0 to 2025.1, Gradle 8 and 9
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the two versions that matter: the Boot version in the report and the Spring Cloud BOM version in your build.

    ./gradlew dependencies --configuration runtimeClasspath | grep -i "spring-cloud-dependencies\|spring-boot-starter "
  2. 2Match what you see, then jump to its fix

    1. 1The report names your Boot version and suggests other versions in its Action section.The release train does not match the Boot generationFix
    2. 2The build used to work and broke only after a Spring Boot version change.You upgraded or downgraded Boot and left the train behindFix
    3. 3You have tested your setup and the verifier is the only thing in the way.You accept the risk and want to bypass the checkFix

What does the error look like?

  • APPLICATION FAILED TO START
  • Your project setup is incompatible with our requirements due to following reasons:
  • Spring Boot [2.7.0] is not compatible with this Spring Cloud release train

Cause 1 of 3

The release train does not match the Boot generation

1Check

Look your Boot generation up in the release train table of the Spring Cloud project page. For example, 2021.0.x pairs with Boot 2.6.x and 2.7.x (2.7.x from 2021.0.3), 2023.0.x with 3.2.x and 3.3.x, and 2025.0.x with 3.5.x.

grep -rn "springCloudVersion\|spring-cloud-dependencies" build.gradle* gradle/libs.versions.toml

2Fix

Change the Spring Cloud BOM version to a train that supports your Boot generation. Note that Boot 2.7.0 needs 2021.0.3 or later of the train, not an earlier 2021.0.x release.

ext {
    set('springCloudVersion', "2021.0.3")
}
dependencyManagement {
    imports {
        mavenBom "org.springframework.cloud:spring-cloud-dependencies:${springCloudVersion}"
    }
}

3Verify

Start the application again.

./gradlew bootRun

Confirmed by spring.io

Did this fix it?

Cause 2 of 3

You upgraded or downgraded Boot and left the train behind

1Check

Each Spring Cloud train lists one or two supported Boot generations on the project page, so a Boot upgrade usually needs a new train.

grep -n "org.springframework.boot" build.gradle*

2Fix

Move the train and Boot together. If you must keep the train, change Boot to one of the versions that the Action section of the report lists.

plugins {
    id 'org.springframework.boot' version '3.5.0'
}
ext {
    set('springCloudVersion', "2025.0.0")
}

3Verify

Run the tests and start the application.

./gradlew test bootRun

Confirmed by spring.io

Did this fix it?

Cause 3 of 3

You accept the risk and want to bypass the check

1Check

The verifier only looks at the Spring Boot version. Spring Cloud Commons documents a property that turns it off and one that sets your own list of accepted versions.

grep -rn "compatibility-verifier" src/main/resources

2Fix

Set the property, preferably the list of accepted Boot versions rather than turning the check off.

# application.properties
spring.cloud.compatibility-verifier.compatible-boot-versions=3.5.x
# or switch the check off
spring.cloud.compatibility-verifier.enabled=false

3Verify

Start the application.

./gradlew bootRun

Confirmed by docs.spring.io

Did this fix it?

How do I stop it coming back?

  • Import the Spring Cloud BOM once, and change the train and Boot in one commit.
  • Check the compatibility table before accepting an automated Boot version bump.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Spring Boot will not start because port 8080 is already taken

Action: Identify and stop the process that's listening on port 8080 or configure this application to listen on another port.

Spring Boot listens on 8080 unless told otherwise, and only one process can own a port.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.