Spring Boot 4 dropped in November 2025 alongside Spring Framework 7.0. It is the most significant release since the jump to Jakarta EE in Boot 3.0. Here is what changed, what broke in real projects, and exactly how to handle it.
1. The Context: Why This Release Matters
If you have been following the Spring ecosystem for a while, you already know that major releases tend to bring surprises — and not always the pleasant kind. However, as the official Spring Boot 4.0 Release Notes make clear, this one is different in character from Boot 3.0’s infamous javax-to-jakarta upheaval.
That said, “not as bad as 3.0” does not mean “effortless.” There are real breaking changes in this release — particularly around modularization, Jackson 3, Spring Security 7 defaults, and JSpecify null safety — and teams that simply bump the version number without preparation are going to hit walls. The good news is that, with the right checklist, the migration is very manageable.
Official SourceThe full, authoritative migration notes live at the Spring Boot 4.0 Migration Guide on GitHub. Read it alongside this article — it is kept up to date as the patch releases roll out.
Furthermore, this upgrade is not just a Spring Boot decision. Because Boot 4 ships on top of Spring Framework 7.0, it also pulls in Spring Security 7, Spring Data 2025.1, Hibernate 7.1, and a whole constellation of major dependency bumps. In other words, you are really doing several migrations at once. Understanding that scope upfront saves a lot of debugging time later.
2. Release Timeline
Before diving into the changes themselves, it helps to understand how this release was staged — because the milestones gave teams months of warning.
M1- May 2025- First Milestone (4.0.0-M1)
Published to Maven Central for the first time, making it far easier to experiment with milestone builds in real projects.
RC- October 2025- Release Candidate 1
API freeze. Most breaking changes were fully documented at this stage. The Spring team strongly recommended that teams begin assessment.
GA- November 20, 2025- General Availability
Spring Boot 4.0 GA ships alongside Spring Framework 7.0. The Spring portfolio — Security, Batch, Data, Integration, and more — all release major versions simultaneously.
4.1- May 2026 (expected)- Spring Boot 4.1
The next minor release follows the established pattern of major-in-November, minor-in-May. Teams can plan migrations with this cadence in mind.
3. The Breaking Changes You Need to Know
Let’s get into specifics. Rather than listing every configuration property rename (the migration guide handles that exhaustively), the following are the changes that consistently caught teams off guard in real migrations.
1. Module Architecture and Starter Restructuring
This is arguably the biggest structural shift in Boot 4. The framework has been fully modularized: each module now lives under its own org.springframework.boot.<module> package. That means any code that reached into internal Boot packages — something that was always discouraged but widely done — will produce compile errors immediately.
Consequently, the old monolithic parent starters have been split. The Spring team provides “classic” starters as a migration bridge, but those are deprecated and will eventually be removed. More importantly, the official guide explicitly warns that supporting both Boot 3 and Boot 4 within the same artifact is strongly discouraged — a relevant constraint for library authors and shared platform teams.
If your organization maintains shared Spring Boot starters or internal libraries, the modularization change requires deliberate attention. The classic starters are available as a temporary bridge, but planning migration away from them early avoids a second migration cycle later.
2. Undertow Removed
Spring Boot 4 requires a Servlet 6.1 baseline, and Undertow does not yet implement Servlet 6.1. As a result, Undertow has been completely removed as an embedded server option. If your application uses spring-boot-starter-undertow, you must switch to Tomcat or Jetty before upgrading. This is a straightforward swap in most cases, but it needs to happen before you bump the Boot version — otherwise the build fails immediately.
3. Spring Security 7 Defaults
Spring Security 7 ships with Boot 4 and changes several defaults that will silently break REST APIs that worked fine before. Specifically, CSRF protection is now enabled for API endpoints by default — previously it only applied to form-based applications. Endpoints that do not send CSRF tokens will return 403 errors without any obvious explanation in the logs.
Additionally, the authorizeRequests() method has been fully removed. Any security configuration still using it must be migrated to authorizeHttpRequests(). The OAuth2 client configuration properties were also restructured, so spring.security.oauth2.client properties need a review.
4. JSpecify Null Safety Annotations
Spring Boot 4 introduces JSpecify nullability annotations across the framework APIs. For most Java developers using standard IDEs, this is largely invisible. However, two groups will notice it immediately: Kotlin developers (because Kotlin’s compiler enforces null contracts) and teams using null-checker build tools. In those cases, previously-passing builds may fail because types that were previously assumed non-null are now explicitly annotated as nullable, or vice versa.
5. Jackson 3 and Package Relocation
Boot 4 prefers Jackson 3, which brings a group/package migration from com.fasterxml.jackson to tools.jackson. The shift affects custom serializers, deserializers, and any code importing Jackson internals. Existing Jackson 2 dependencies still work during a transition period, but the behavioral differences in date/time formatting, null handling, and default type handling can cause runtime failures that compile cleanly.
6. Removed Deprecated APIs
As with any major release, everything deprecated in Spring Boot 3.x is gone in Boot 4. That includes WebSecurityConfigurerAdapter, RestTemplate auto-configuration (now opt-in), @ConfigurationProperties binding to public fields, and a long list of other items. The migration guide covers each removal with its recommended replacement.
| Breaking Change | Severity | Affected Code | Fix Summary |
|---|---|---|---|
| Module restructuring / package moves | HIGH | Internal Boot imports, shared libraries | Use public APIs only; adopt modular starters |
| Undertow removed | HIGH | Apps with spring-boot-starter-undertow | Switch to Tomcat or Jetty before upgrading |
| Security 7: CSRF on by default for APIs | HIGH | REST APIs without CSRF tokens | Explicitly disable for stateless APIs or add CSRF support |
authorizeRequests() removed | MEDIUM | Security config classes | Migrate to authorizeHttpRequests() |
| JSpecify null annotations | MEDIUM | Kotlin projects, null-checker tools | Review and fix null contract violations |
| Jackson 3 package relocation | MEDIUM | Custom Jackson code, serializers | Update imports; test serialization behavior carefully |
| Removed Boot 3.x deprecated APIs | LOW–MED | Anything using deprecated Boot 3 methods | Clean deprecation warnings before upgrading |
@ConfigurationProperties public fields | LOW | Config properties bound to public fields | Switch to private fields with getters/setters |
4. New Defaults That Silently Change Behavior
Beyond what breaks at compile time, several default behavior changes can cause runtime surprises. These are worth calling out separately because they do not produce errors — they just produce wrong results.
First, PropertyMapper no longer maps null source values by default. If your application relied on null values flowing through property mapping, you now need to explicitly call .always(). Second, Logback’s default charset handling has been aligned with UTF-8 expectations, which can affect log output encoding in environments with non-default charsets. Third, the RestTemplate auto-configuration is now opt-in rather than automatic, meaning applications that relied on an auto-wired RestTemplate without declaring one will fail at startup.
Furthermore, repository query methods are now processed at build time by default via Spring Data 2025.1. This improves startup performance and GraalVM native image compatibility — but it also means that malformed queries, previously caught at runtime, now cause build failures. That is ultimately a good thing, but teams should expect some initially-surprising build errors when they first upgrade.
Many of these new defaults represent meaningful improvements. CSRF protection for APIs is genuinely better security. Build-time query validation catches errors earlier. The transition is a bit bumpy, but the destination is better in almost every case.
5. What Actually Broke in Real Projects
Theory is one thing — but what did teams actually run into when they upgraded? Based on real migration reports and community discussions, a clear pattern emerged.
The single most common failure was REST APIs returning 403 after upgrade, caused by the new CSRF-on-by-default behavior in Spring Security 7. Teams that had written stateless REST APIs without CSRF configuration — which was perfectly correct in Boot 3 — suddenly had all their API calls rejected. The fix is simple, but only once you know why it’s happening.
The second most common failure was Jackson serialization producing unexpected output. Custom date formats, null field handling, and number serialization (especially around BigDecimal) all behaved slightly differently under Jackson 3 defaults. Integration tests that compared JSON output character-by-character started failing, even though the core logic was unchanged.
Third in line was the Kotlin null-safety compilation failures triggered by JSpecify annotations. Teams using Kotlin found that previously-compiling code suddenly had type mismatches because Spring APIs that were previously assumed non-null are now annotated as potentially nullable. The fixes were usually small, but there could be many of them spread across a codebase.
“If you treat it as a platform migration instead of a ‘version bump’, the upgrade is predictable and safe.”— Spring Boot 4.0 Migration Guide, Production Teams Edition
Finally, teams running Undertow as their embedded server hit an immediate hard stop — no boot, no workaround, no compatibility shim. Switch to Tomcat or Jetty first, full stop. This was relatively rare (Undertow was never the default), but for teams that made a deliberate choice to use Undertow, it was an unwelcome surprise.
Most Common Failure Categories During Boot 3 → 4 Migration
6. Performance Numbers
One thing that often gets buried in migration articles is the “why bother?” question. If the migration is genuinely painful, what do you get in return? The performance improvements in Boot 4 are real and measurable, so they deserve direct attention.
Thanks to Hibernate 7.1’s internal switch from synchronized blocks to ReentrantLock, database-heavy applications see noticeably better throughput under virtual threads — something Java 21+ enables and Boot 4 auto-configures. Spring Data 2025.1’s shift to JPQL strings for derived queries yields roughly 3.5× better query throughput on benchmarks. Meanwhile, the reduced SessionFactory bootstrap memory in Hibernate 7.1 cuts startup memory by around 12%, according to the Katyella migration team’s findings.
Spring Boot 3.5 vs 4.0 — Key Performance Metrics
On top of that, Boot 4’s new spring-boot-starter-opentelemetry — a first-party observability starter — replaces what previously required manual Micrometer + Prometheus wiring. That is not a performance gain per se, but it significantly reduces the operational complexity of running Boot applications in production.
7. The Migration Path, Step by Step
With all of the above in mind, here is the practical path from Boot 3 to Boot 4. The most important insight from the Spring team themselves is this: do not try to go from Boot 3.x directly to 4.0 in one jump if you are more than one minor version behind.
Step 1 — Upgrade to Spring Boot 3.5.x First
Before touching Boot 4 at all, make sure you are on the latest 3.5.x release. This ensures you are on the newest 3.x dependency line and, crucially, gives you the opportunity to clear all deprecation warnings. Every warning you ignore now becomes a compile error in Boot 4.
Step 2 — Deal with Undertow (if applicable)
If you are using Undertow, switch to Tomcat or Jetty now, while still on Boot 3.5. Verify that your application starts and passes all tests before moving on.
Step 3 — Bump to Spring Boot 4.0
Update your build file. In Maven:
<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>4.0.0</version> </parent>
In Gradle:
id 'org.springframework.boot' version '4.0.0'
After this, compile. Do not run yet — just compile and read every error carefully.
Step 4 — Fix Compile Errors
Address removed APIs and package moves. For most applications the biggest categories are: Security config (replace authorizeRequests() with authorizeHttpRequests()), Jackson import paths, and any code reaching into internal Boot packages. If you have a Kotlin project, work through JSpecify-triggered null-safety errors methodically.
Step 5 — Fix Spring Security CSRF Configuration
For stateless REST APIs, explicitly disable CSRF in your security configuration. In Boot 4 with Spring Security 7:
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
.csrf(csrf -> csrf.disable()) // for stateless APIs
.authorizeHttpRequests(auth -> auth
.anyRequest().authenticated()
);
return http.build();
};
Step 6 — Run Integration Tests
Pay particular attention to tests that touch security configuration, JSON serialization output, database queries, and HTTP client behavior. These four areas are where the new defaults produce the most subtle behavioral changes. If your tests use exact JSON string matching, expect some failures related to Jackson 3 formatting differences.
Step 7 — Consider OpenRewrite for Large Codebases
If you are working with a large codebase or many microservices, OpenRewrite can automate the mechanical parts of the migration — package renames, deprecated API replacements, configuration property updates. It does not catch everything, but it handles enough of the boilerplate that it is worth running before manual review.
| Migration Step | Effort | Risk if Skipped | Automation Available |
|---|---|---|---|
| Upgrade to Boot 3.5.x first | Low | High — dependency drift adds hidden failures | Version bump only |
| Remove Undertow dependency | Low | Critical — build fails immediately | Manual |
| Fix removed deprecated APIs | Medium | High — compile errors | OpenRewrite (partial) |
| Security CSRF configuration | Low | High — silent 403 errors on all API calls | Manual |
| Jackson 3 behavior verification | Medium | Medium — runtime serialization differences | Integration tests |
| Kotlin null-safety fixes | Medium | High (Kotlin only) — compile errors | IDE quick-fixes |
| Migrate to modular starters | Medium | Low short-term — classic starters still work | OpenRewrite (partial) |
8. What We Have Learned
Spring Boot 4.0 is a meaningful platform upgrade — not a routine version bump. It arrives on top of Spring Framework 7.0, Jakarta EE 11, Hibernate 7.1, Spring Security 7, and Spring Data 2025.1, which means the blast radius of the upgrade is wider than the Boot version number alone suggests. The breaking changes are real but manageable: modularized packages require clean internal API usage, Undertow users must switch servers, Spring Security 7’s CSRF defaults will silently break REST APIs, and JSpecify null annotations will catch Kotlin teams off guard.
Fortunately, the migration tooling has genuinely improved. OpenRewrite automates the mechanical changes, the Spring team publishes a thorough migration guide, and the milestone-to-GA timeline gave teams months of advance notice. The performance gains — particularly for virtual-thread-heavy workloads and query-intensive applications — make the upgrade worth doing. For new projects, start on Boot 4 today. For existing applications, upgrade to Boot 3.5.x first, clear all deprecation warnings, and then tackle Boot 4 as a deliberate, staged platform migration rather than a casual version bump.
awesome Knowledge sharing