Step‑by‑Step Guide to Upgrade Spring Boot 3.x to 4.0 Without Pain

Why Upgrade?

Spring Boot 4.0.0 is based on Spring Framework 7.0, supports Java 25, introduces HTTP Service Clients, native API version management, JSpecify null‑safety, upgrades core dependencies (Jackson 3.0, Tomcat 11, Hibernate 7.1), modular design, Gradle 9 support, Redis static master‑slave configuration, and removes Undertow.

Version Change Overview

Official upgrade path to avoid most issues: 3.3/3.4 → 3.5 → 4.0 .

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

Detailed Upgrade Steps

Step 1: Upgrade Gradle

Spring Boot 4.0 requires Gradle 8.14 or newer. Run the wrapper upgrade command:

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

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

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

Step 2: Update Dependency Versions

Edit gradle/libs.versions.toml to declare 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" }

The Version Catalog centralizes dependency versions for the whole project.

Step 3: Modular Refactor (Starter Changes)

Replace the old web starter with the new webmvc starter:

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

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

Full build.gradle snippet:

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

Jackson 3 moved its packages from com.fasterxml.jackson to tools.jackson. Update imports and exception types accordingly. 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
}

Step 5: Redisson 4.0 API Migration

Redisson 4.0 moved stream‑related classes to a new package. Update imports such as:

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

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

Affected classes:

infrastructure/redis/RedisService.java

modules/resume/listener/AnalyzeStreamConsumer.java

modules/knowledgebase/listener/VectorizeStreamConsumer.java

Validate the Upgrade

Run the following commands to compile, test, and start the application:

# compile
./gradlew :app:compileJava

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

# start
./gradlew :app:bootRun

Successful startup logs should contain entries such as:

:: 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

References

Spring Boot 4.0 release announcement

Spring Boot 4.0 Migration Guide

Spring AI 2.0.0‑M1 release announcement

Redisson changelog

Jackson 3 release notes

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

Conclusion

Upgrading to Spring Boot 4.0 mainly involves:

Build tool upgrade to Gradle 8.14+

Modular starter change: starter-web → starter-webmvc Jackson 3 package rename

Third‑party library compatibility (Redisson, Spring AI, etc.)

Following the official path 3.3 → 3.5 → 4.0 avoids most pitfalls; most issues stem from package name changes that can be resolved with a global search‑replace.