How to Seamlessly Upgrade to Spring Boot 4.0: A Step‑by‑Step Guide

Why upgrade to Spring Boot 4.0

Spring Boot 4.0 is based on Spring Framework 7.0 and requires Java 25. It introduces HTTP Service Clients, native API version management, JSpecify null‑safety, and upgrades core libraries (Jackson 3.x, Tomcat 11, Hibernate 7.x, etc.). Using the latest stable release provides security updates and new capabilities.

Version change overview

Spring Boot: 3.3.6 → 4.0.1

Spring Framework: 6.x → 7.x

Spring AI: 1.1.2 → 2.0.0‑M1

Redisson: 3.24.3 → 4.0.0

Gradle: 8.8 → 8.14

Hibernate: 6.x → 7.2.0.Final

Tomcat: 10.x → 11.0.15

Jackson: 2.x → 3.x

iText: 7.2.5 → 8.0.5

MapStruct: 1.5.5.Final → 1.6.3

Upgrade steps

Step 1 – Upgrade Gradle

Spring Boot 4.0 requires Gradle 8.14+. Upgrade the wrapper:

# Temporary use old Spring Boot to run wrapper upgrade
./gradlew wrapper --gradle-version=8.14

Then edit gradle/wrapper/gradle-wrapper.properties:

distributionUrl=https\://services.gradle.org/distributions/gradle-8.14-bin.zip

Step 2 – Update dependency versions

Modify gradle/libs.versions.toml to the new versions:

[versions]
spring-boot = "4.0.1"
spring-ai = "2.0.0-M1"
redisson = "4.0.0"
mapstruct = "1.6.3"
aws-sdk = "2.29.51"
itext = "8.0.5"
lombok = "1.18.36"
junit-jupiter = "5.12.0"

[plugins]
spring-boot = { id = "org.springframework.boot", version.ref = "spring-boot" }
spring-dependency-management = { id = "io.spring.dependency-management", version = "1.1.7" }

Step 3 – Modular refactor (starter changes)

Replace the old web starter with the new MVC starter:

// before
implementation 'org.springframework.boot:spring-boot-starter-web'

// after
implementation 'org.springframework.boot:spring-boot-starter-webmvc'

Full build.gradle dependency block after the change:

dependencies {
    // Spring Boot Starters (Boot 4.0 modular design)
    implementation 'org.springframework.boot:spring-boot-starter-webmvc'
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'

    // Spring AI 2.0
    implementation "org.springframework.ai:spring-ai-starter-model-openai:${libs.versions.spring.ai.get()}"
    implementation "org.springframework.ai:spring-ai-starter-vector-store-pgvector:${libs.versions.spring.ai.get()}"

    // Redisson 4.0
    implementation "org.redisson:redisson-spring-boot-starter:${libs.versions.redisson.get()}"

    // iText 8
    implementation "com.itextpdf:itext-core:${libs.versions.itext.get()}"
    implementation "com.itextpdf:font-asian:${libs.versions.itext.get()}"
}

Step 4 – Jackson 3 migration (breaking change)

Jackson 3 moves its packages from com.fasterxml.jackson to tools.jackson. Update all imports, e.g.: com.fasterxml.jackson.databind.ObjectMapper →

tools.jackson.databind.ObjectMapper

com.fasterxml.jackson.core.type.TypeReference

→

tools.jackson.core.type.TypeReference

com.fasterxml.jackson.core.JsonProcessingException

→ tools.jackson.core.JacksonException Example code before and after:

// before
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;

try {
    String json = objectMapper.writeValueAsString(data);
} catch (JsonProcessingException e) {
    // handle
}

// after
import tools.jackson.core.JacksonException;
import tools.jackson.core.type.TypeReference;
import tools.jackson.databind.ObjectMapper;

try {
    String json = objectMapper.writeValueAsString(data);
} catch (JacksonException e) {
    // handle
}

Perform a project‑wide replace of com.fasterxml.jackson with tools.jackson in all affected classes (e.g., PdfExportService, RedisService, etc.).

Step 5 – Redisson 4.0 API migration

Redisson 4.0 reorganised several stream‑related classes. Update imports, for example:

// before
import org.redisson.api.StreamMessageId;

// after
import org.redisson.api.stream.StreamMessageId;

Classes that need the change:

infrastructure/redis/RedisService.java

modules/resume/listener/AnalyzeStreamConsumer.java

modules/knowledgebase/listener/VectorizeStreamConsumer.java

Validate the upgrade

Run the following Gradle commands:

# Compile the project
./gradlew :app:compileJava

# Build and run tests
./gradlew :app:build

# Start the application
./gradlew :app:bootRun

Successful startup logs should contain entries similar to:

.   ____          _          __ _ _
/\ / ___'_ __ _(_)_ __  __ _ \ \ \
( ( )\___ | '_ | _ \| '_ \ / _` | \ \ \
\/  ___)| |_)| | | | | || (_| |  ) ) ) )
'  |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot ::                (v4.0.1)
... Tomcat initialized with port 8080 (http)
... Starting Servlet engine: [Apache Tomcat/11.0.15]
... Redisson 4.0.0
... HHH000001: Hibernate ORM core version 7.2.0.Final

Summary of changes

Build tool upgrade : Gradle 8.14+

Starter change : spring-boot-starter-web → spring-boot-starter-webmvc Jackson 3 migration : package rename from com.fasterxml.jackson to tools.jackson Third‑party compatibility : Redisson, Spring AI and other libraries upgraded to versions that support Spring Boot 4.0

Follow the official upgrade path 3.3 → 3.5 → 4.0 to avoid most issues; the majority of problems stem from the Jackson package rename and can be resolved with a global search‑replace.

Commit containing all changes: https://github.com/Snailclimb/interview-guide/commit/f7bb05980b725c8658f93a4c511bf4b2ec616b82

References

Spring Boot 4.0 release announcement: https://spring.io/blog/2025/11/20/spring-boot-4-0-0-available-now/

Spring Boot 4.0 Migration Guide: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide

Spring AI 2.0.0‑M1 release announcement: https://spring.io/blog/2025/12/11/spring-ai-2-0-0-M1-available-now/

Redisson changelog: https://github.com/redisson/redisson/blob/master/CHANGELOG.md

Jackson 3 release notes: https://github.com/FasterXML/jackson/wiki/Jackson-Release-3.0