A Spring Boot 3 to 4 migration should start with a working application on the latest 3.5.x patch. From there, the important work is dependency and package changes, JSON compatibility, security configuration, and tests that exercise real application behavior.
Java 17 remains the minimum for Spring Boot 4.0. You do not have to upgrade to Java 21 just to adopt Boot 4. This guide covers the 3.5-to-4.0 transition, then the checks for moving from 4.0 to 4.1.
What’s New in Spring Boot 4
Modular Auto-Configuration and Starters
Boot 4 splits its large jars into smaller modules, with application and test starters for individual technologies. A third-party library on the classpath may no longer bring the Boot integration you previously received indirectly. Map each integration to its starter before fixing missing beans one at a time. The official module tables cover both production and test dependencies.
Spring Framework 7 and Jakarta EE 11
Boot 4 builds on Spring Framework 7 and the Jakarta EE 11 baseline. The relevant specification versions include Servlet 6.1, Persistence 3.2 and Validation 3.1. Let Boot manage the compatible dependency set. Retaining a Framework 6 override or an older servlet API can leave an application with incompatible classes even when dependency resolution succeeds. These versions are listed in the 4.0 release notes.
JSpecify Null-Safety Annotations
Spring Boot and Framework now describe API nullability with JSpecify. Kotlin and Java builds using a null checker can report failures where types are now explicitly nullable or non-nullable. Review overrides and nullable values at framework boundaries. The Framework null-safety documentation explains the annotations and tooling; adding them does not insert runtime null checks into your application.
Declarative HTTP Clients
HTTP interface clients predate Boot 4. The new part is Framework 7’s @ImportHttpServices registration and Boot’s auto-configuration for HTTP service clients. Annotated interfaces can be registered in groups that share client configuration. Follow the Boot HTTP service client documentation. When adopting this during an upgrade, test authentication, timeouts and error handling against the behavior of the client being replaced.
OpenTelemetry Starter
The new spring-boot-starter-opentelemetry configures the OpenTelemetry SDK and brings dependencies for exporting metrics and traces through OTLP. That is the scope described in the 4.0 release notes. Check existing exporters and agents before adding it, then verify that your backend receives the expected telemetry without duplicates. Treat logging export as a separate configuration check.
Hibernate 7 and Spring Data 2025.1
Boot 4 adopts Hibernate 7 and Spring Data 2025.1. Repository interfaces may need little editing, but custom Hibernate integrations need a separate review. Run persistence tests against the database engine you deploy, including detached entities and transaction boundaries. The ORM upgrade can affect behavior beyond the repository methods visible in your application.
Spring Security 7
Security 7 removes older configuration APIs and changes request matcher support. Inventory custom filter chains and explicitly constructed matchers before upgrading. Step 4 covers the lambda DSL; the pitfalls section covers tests that still compile but exercise different security behavior.
Jackson 3
Jackson 3 becomes Boot’s preferred JSON library. This affects dependencies and mapper customization as well as imports. A library that exposes a Jackson 2 mapper cannot be assumed to accept a Jackson 3 mapper. Keep saved request and response payloads for the compatibility checks in Step 3.
Check the Requirements Before Changing Dependencies
According to the Spring Boot 4.0 system requirements, the baseline is Java 17 and Spring Framework 7. Build support includes Maven 3.6.3 or later and Gradle 8.14 or later in the 8.x line, or Gradle 9.x. Native-image builds require GraalVM 25 or later.
Check the JDK actually used by the build, rather than relying on the version installed in your terminal:
java -version
./mvnw -version
# For a Gradle project:
./gradlew --version
Record the versions used in CI, containers, and production too. Keep a separate list of dependencies your team versions outside the Boot dependency management, including Spring Cloud, database drivers, and internal starters.
If you are still on Boot 2, first work through the Spring Boot 2.7 to 3.x migration. Combining that namespace migration with the Boot 4 changes makes failures harder to diagnose.
Step-by-Step Migration Process
Step 1: Establish a Spring Boot 3.5 Baseline
Move to the latest available 3.5.x maintenance release, commit the dependency changes, and get the test suite passing. Resolve deprecation warnings before moving to 4.0. This is the upgrade sequence in the official Boot 4 migration guide.
Save representative HTTP responses, database results, authentication flows, and batch restart behavior as regression fixtures. A clean compile is only the first check: changed defaults can alter behavior without producing compiler errors.
Step 2: Update Application and Test Starters
Update your Boot parent or BOM and build plugin to the selected 4.0.x maintenance release. Review application and test dependencies together, including moved imports. Start with the integrations you actually use:
| Application concern | Boot 4 dependency to review |
|---|---|
| Spring MVC | spring-boot-starter-webmvc |
| MVC test support | spring-boot-starter-webmvc-test |
| Security test support | spring-boot-starter-security-test |
| Flyway migrations | spring-boot-starter-flyway |
| Liquibase migrations | spring-boot-starter-liquibase |
| Persistent Spring Batch metadata | spring-boot-starter-batch-jdbc |
For an MVC application, the relevant Maven fragments are:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc-test</artifactId>
<scope>test</scope>
</dependency>
Let your chosen Boot parent or BOM manage these versions. The old web starter is deprecated, so its continued availability does not mean your dependency review is finished. Use the official migration guide’s starter tables for the technologies your application uses.
Step 3: Treat Jackson 3 as a Compatibility Change
Boot 4 prefers Jackson 3. The Jackson 3 migration documentation explains the change from com.fasterxml.jackson to tools.jackson for most packages. Jackson annotations remain under com.fasterxml.jackson.annotation, so a global search-and-replace is inappropriate.
For example, review imports such as:
// Jackson 2
import com.fasterxml.jackson.databind.ObjectMapper;
// Jackson 3
import tools.jackson.databind.ObjectMapper;
Check custom serializers, registered modules, mapper customization, and libraries that expose Jackson types. Then compare JSON fixtures before and after the upgrade: dates, enum values, null fields, error responses, and polymorphic payloads are useful starting points.
Boot’s migration guide also documents renamed customization classes and the temporary Jackson 2 compatibility module. Use that bridge only with an explicit plan to remove it. A project that compiles with both Jackson versions still needs serialization tests.
Step 4: Migrate the Spring Security Configuration
Spring Security 7 removes authorizeRequests and the chained .and() configuration style. Use authorizeHttpRequests with the lambda DSL. The changes are listed in Spring Security 7’s release notes.
@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http.authorizeHttpRequests(auth -> auth
.requestMatchers("/public/**").permitAll()
.anyRequest().authenticated()
);
return http.build();
}
This fragment shows authorization rules; preserve your application’s authentication configuration alongside them.
Step 5: Verify Runtime Behavior
Work through the breaking changes below before deploying. Run the packaged application with production-like configuration and exercise database migrations and job restarts. Compare the telemetry received by your backend with your 3.5 baseline, including alerts and health checks. The OpenTelemetry guide covers that path.
Breaking Changes You Need to Know
The official 4.0 migration guide documents these changes. Some cause compiler errors; others change a working application’s defaults.
Removed Deprecated APIs
Classes, methods and properties deprecated in Boot 3.x are removed in 4.0. Clear warnings while still on 3.5, including those in internal starters. Compilation alone cannot find old class names stored in configuration resources, so inspect integrations that register Boot infrastructure by name too.
Undertow Removed
Boot 4.0 removes Undertow support because of its Servlet 6.1 baseline. Replace the Undertow starter with a supported server such as Tomcat or Jetty. Audit server configuration and test uploads, forwarded headers and graceful shutdown. Renaming server.undertow properties does not replace the server dependency.
Jakarta EE 11 Alignment
Boot 3 applications already use the jakarta.* namespace. This upgrade raises specification versions within that namespace. Check explicit API dependencies and libraries that integrate with servlet or persistence internals. WAR deployments also need a Servlet 6.1-compatible container; changing only the embedded server dependencies will not upgrade an external application server.
Configuration Property Renames
Add the properties migrator temporarily while diagnosing renamed or removed settings:
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-properties-migrator</artifactId>
<scope>runtime</scope>
</dependency>
For example, Spring Session Redis properties move from spring.session.redis.* to spring.session.data.redis.*. Apply reported changes to configuration files and deployment overrides. Remove the migrator, restart, and rerun affected tests. Its temporary runtime mappings should not become a hidden production dependency.
DevTools LiveReload Disabled by Default
Boot 4.0 disables LiveReload by default. Set spring.devtools.livereload.enabled=true if your development workflow needs it. This setting concerns browser reload support. Check the additional 4.1 deprecation below before building more tooling around it.
Spring Batch In-Memory by Default
The regular spring-boot-starter-batch uses Batch’s database-free, in-memory mode. It no longer stores job metadata in your existing database. For a JDBC job repository, switch to spring-boot-starter-batch-jdbc. Keeping a datasource is insufficient. Test an interrupted job across an application restart and verify the persisted execution state before enabling scheduled jobs.
Use OpenRewrite for the Mechanical Work
The recipe ID is org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0. Consult the current recipe documentation for its edition, artifact availability, and repository setup before running it. Do not assume an old plugin version and an unpinned LATEST recipe will reproduce someone else’s migration.
With the appropriate plugin and recipe dependency configured, generate a patch first:
# Maven project with Rewrite configured
./mvnw rewrite:dryRun \
-Drewrite.activeRecipes=org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0
# Or Gradle project with the same recipe configured
./gradlew rewriteDryRun
Review that patch, apply it on a branch, and run the regression suite. My OpenRewrite walkthrough covers how to organize the migration into reviewable changes.
Common Pitfalls
Third-Party Library Compatibility
Check compatibility statements for the exact versions you use, especially Spring Cloud and internal starters outside Boot’s dependency management. Inspect transitive dependencies when a library brings older Spring or Jackson types. A successful dependency download says nothing about binary compatibility. Exercise the library’s actual integration in a small test before changing application code around a linkage error.
Security Test Failures
CSRF protection was already enabled by default in Spring Security 6. A new 403 does not mean Boot 4 suddenly enabled it. The Security 6.5 documentation describes that existing behavior.
Check which filter chain handles the request, its credentials and its authorization rules. Include a valid CSRF token where required and test the missing-token case. Keep protection for browser flows with automatically supplied credentials. Also review explicit MvcRequestMatcher or AntPathRequestMatcher usage: Security 7 replaces them with PathPatternRequestMatcher. Do not disable security to make the tests pass.
Modular Starter Discovery
A missing bean after the split often means the relevant auto-configuration module is absent. Inspect the dependency tree and Boot’s condition evaluation report. Distinguish an absent module from a configuration whose conditions did not match. Check test starters separately when only a slice test fails. The Boot 4 test errors guide covers moved imports and other test failures.
Hibernate SQL and Behavior Changes
Hibernate 7 removes Session.save, update and saveOrUpdate, as documented in its migration guide. Choose persist for new entities and merge for detached ones, accounting for the managed instance returned by merge. Life after saveOrUpdate covers entity state and Envers audit behavior.
Compare generated SQL and query plans for important queries, along with result ordering and flush behavior. Tests asserting exact SQL strings may need review, but do not dismiss a changed query without checking its database behavior. Include a real write and read-back test so mocked repositories cannot hide a broken persistence path.
Should You Upgrade Now?
I would move an application with compatible dependencies and useful regression tests onto a supported Boot 4 line. New projects can start there too, after checking their required integrations. Use 4.0 as a tested migration checkpoint when continuing to 4.1.
Waiting for an incompatible dependency can be reasonable if there is a concrete replacement or upgrade plan. Waiting indefinitely on 3.5 has a support consequence: Spring’s June 25, 2026 release announcement identifies 3.5.16 as the final OSS release of that line and directs users to 4.0 or 4.1 for continued OSS support. Commercial support is a separate option. Establish who owns the dependency blocker and when you will revisit it.
Migration Checklist
- Latest selected Boot 3.5 patch passes regression tests before the major upgrade.
- JDK, build plugins, and independently versioned libraries support the chosen Boot 4 patch.
- Application and test starters match the technologies in use.
- Jackson customization and representative JSON contracts pass compatibility tests.
- Authentication, authorization, and CSRF tests pass for each filter chain.
- Server behavior, database queries, and batch restart behavior are verified.
- Properties migrator is removed and the application still starts correctly.
- Telemetry, health checks, and rollback are exercised in staging.
Benchmark startup, CPU, memory, and latency against your own baseline. This upgrade does not guarantee a percentage improvement, and changing the JDK, framework, collector, and resource limits together makes the result harder to explain.
Moving On to Spring Boot 4.1
Get the 4.0 checklist green first. In my Petclinic run, the 4.0-to-4.1.2 step took 1m18s including build and tests. The full upgrade path finished green three times. The recorded upgrade path shows the preceding work. That timing describes this sample, not an estimate for another application.
The official 4.1 release notes identify the following checks for an application already on 4.0.
Clear Deprecations and Update Build Scripts
Classes, methods and properties deprecated in 4.0 are removed in 4.1. Resolve those warnings before changing the Boot version, including calls inside shared libraries.
Search Dockerfiles and packaging scripts for -Djarmode=layertools. That jar mode is removed; migrate to tools and verify the extraction command and resulting directory layout.
Maven’s -DskipTests no longer skips test AOT processing in the Spring Boot Maven Plugin. The plugin only honors maven.test.skip for that decision. If a packaging job intentionally skips test AOT processing, update its invocation to use -Dmaven.test.skip=true. Keep a separate job that runs the tests and relevant AOT checks.
Check JPA Startup and Tomcat Storage
With spring.data.jpa.repositories.bootstrap-mode=deferred, startup now fails if no suitable AsyncTaskExecutor bean exists for the auto-configured LocalContainerEntityManagerFactoryBean. Check the executor configuration under every deployed profile. With lazy, Boot no longer sets that entity manager factory’s bootstrap executor. Recheck any startup assumptions tied to background initialization.
Tomcat’s temporary base directory is now deleted when the application context closes. If your setup needs the directory to survive, configure server.tomcat.basedir with an explicit location. Include shutdown and restart in the test, rather than checking only initial startup.
Retest Configuration Binding
Constructor-bound Optional parameters now receive Optional.empty() instead of null when no value is bound. Review constructor logic and tests for @ConfigurationProperties types that explicitly expect null.
Empty YAML objects are now retained in the resulting PropertySource. Add binding checks for configuration using {}, especially where defaults or profile overrides matter. Assert the resulting configuration object so the test catches changes in the values the application uses.
Check Dependencies and Deprecations
Boot 4.1 requires jOOQ 3.20 or later, which requires Java 21 or later. If you use jOOQ, verify both the build toolchain and runtime image before upgrading. This dependency requirement does not change the Java 17 baseline stated above for Boot 4.0.
The 4.1.0 release notes list Spring Security 7.1.0, Spring Data 2026.0.0, Hibernate 7.4 and Micrometer 1.17.0 among the managed upgrades. Let your chosen Boot patch manage its versions and rerun persistence and security tests.
DevTools LiveReload is deprecated with no replacement. Derby support is also deprecated. Record follow-up work if either is part of your development or test setup.
Review New Auto-Configuration Where It Applies
Boot 4.1 adds Spring gRPC support. Existing gRPC applications should review their starter and configuration choices before enabling Boot’s integration. Spock support returns with Spock 2.4 and Groovy 5; check the test runtime if you maintained a workaround on 4.0.
For HTTP clients fetching user-supplied URLs, evaluate InetAddressFilter. It can block outgoing requests to specific addresses in blocking and reactive clients to help mitigate SSRF. Test the intended address restrictions explicitly.
Review custom Jackson configuration against the new spring.jackson.read.* and spring.jackson.write.* properties for features shared across formats. For OpenTelemetry, check management.opentelemetry.enabled and management.opentelemetry.tracing.sampler against your deployment settings. Verify actual exported traces after changing sampling configuration.
Spring Boot 4.1 Migration Checklist
- Boot 4.0 deprecations are resolved before the version change.
- Packaging uses
tools; Maven jobs handle test AOT processing explicitly. - JPA bootstrap modes and executor beans work in deployed profiles.
- Tomcat directory cleanup and configuration binding are tested.
- jOOQ applications use a compatible Java version; managed dependency changes pass regression tests.
- Relevant new auto-configuration is reviewed and telemetry reaches the backend.
If you need help assessing dependencies or sequencing the rollout, talk through your migration with Katyella.
Related Articles
- Spring Boot 4 Test Errors: Moved Imports and Duplicate Caches
- The Spring Boot 2.7 to 4.1 Upgrade Path That Ran Green Three Times
- Spring Boot 4: What Changed and Whether to Upgrade
- Spring Boot 2.7 to 3.x Migration Guide
- Hibernate 5 to 6 Migration
- OpenTelemetry with Spring Boot
Java Modernization Readiness Assessment
15 questions your team should answer before starting a migration. Takes 10 minutes. Could save you months.