Everything in this guide was tested on Spring Boot 4.0.0, Spring Framework 7.0.0, Spring Security 7.0.0, and Java 21.0.3 (Eclipse Temurin). Behaviour details may differ on milestone or RC builds of Boot 4 — check the release notes if you are running a pre-GA version.
TL;DR
- Spring Boot 4 requires Java 21 minimum — Java 17 is no longer supported.
- All APIs deprecated in Boot 3.x are removed in Boot 4. There are no grace periods.
- Virtual threads are enabled by default; this changes how you reason about concurrency bugs.
- Spring Security’s
HttpSecuritylambda DSL is now the only supported approach — method chaining is gone. - Auto-configuration loading moves from
spring.factoriestoAutoConfiguration.imports— third-party starters will break silently if not updated. - The Observation API (Micrometer) replaces the legacy metrics and tracing wiring — expect startup failures if your custom metrics code isn’t updated.
The Migration Nobody Is Fully Ready For
Every few years, the Spring ecosystem ships a major version that makes us rethink our life choices. Spring Boot 3 brought the Jakarta EE namespace rename — javax.* to jakarta.* — and we spent weeks hunting down transitive dependencies that hadn’t been updated. Spring Boot 4 is a different kind of disruption. The changes are more surgical, spread across the runtime model, security wiring, observability stack, and configuration loading mechanism. Worse, many of the failures are silent — your application starts, but acts weirdly under load.
This guide is for anyone running Spring Boot 3.x in production who’s planning (or being dragged kicking and screaming) toward Boot 4. I’ve put together the actual breaking changes, bad vs. good code examples, and what actually happens internally when things break. No hand-waving, no “just update your pom.xml” nonsense.
When to Migrate (and When NOT to)
Migrate to Spring Boot 4 when:
- Your team is already on Java 21 or committed to upgrading.
- You need first-class virtual thread support without manual configuration.
- You’re building new services and want the latest GraalVM native image improvements.
- Your third-party starters and libraries have Boot 4-compatible releases available.
- You have adequate test coverage (integration tests, not just unit tests) to catch silent regressions.
Do NOT migrate yet if:
- You’re on Java 17 with no near-term plan to upgrade — Boot 4 will not compile on Java 17.
- Your stack relies on a key library (e.g., a JDBC driver, a messaging client) that hasn’t released a Boot 4-compatible version.
- You’re mid-sprint in a production-critical release cycle. Boot 4 migrations deserve a dedicated sprint.
- You have heavy use of deprecated Boot 3 APIs that were never cleaned up. You’ll need to fix those first, or the Boot 4 build will fail before you even start.
Breaking Change #1 — Java 21 Is Non-Negotiable
Spring Boot 4 targets Spring Framework 7, drawing a hard line at Java 21. This isn’t just for compilation — the framework relies on Java 21 features internally.
The practical consequence: setting source/target = 17 causes a hard build failure. Your CI pipeline, Docker images, and runtime environments must all move to JDK 21.
Opinionated Takeaway: Don’t just bump the compiler flag to make it compile. Use this as an excuse to actually rewrite your clunky switch statements using pattern matching.
BAD — Still targeting Java 17 in Maven
<!-- Maven pom.xml - will fail to build with Spring Boot 4 -->
<properties>
<!-- This causes a build failure with Boot 4 / Spring Framework 7 -->
<java.version>17</java.version>
<maven.compiler.source>17</maven.compiler.source>
<maven.compiler.target>17</maven.compiler.target>
</properties>IMPROVED — Targeting Java 21 with release flag
<!-- Maven pom.xml - correct configuration for Spring Boot 4 -->
<properties>
<!-- Java 21 is the minimum supported version -->
<java.version>21</java.version>
<!-- --release 21 is stricter than source/target: also blocks internal JDK API usage -->
<maven.compiler.release>21</maven.compiler.release>
</properties>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>4.0.0</version>
</parent>The --release 21 flag (via maven.compiler.release) is stricter than the old source/target combination — it also gates against accidentally using internal JDK APIs, which is desirable for production code anyway.
Breaking Change #2 — Virtual Threads Are On by Default
Boot 3.2 made virtual threads opt-in. Boot 4 flips this: they now power the embedded Tomcat executor by default. This is a major behavioral shift.
Under heavy traffic, virtual threads allow your server to juggle hundreds of thousands of requests with minimal OS overhead. Benchmarks often show throughput doubling or quadrupling for I/O-heavy workloads, all without tweaking application code.
The catch? Code that was perfectly safe with platform threads can now exhibit subtle bugs due to thread-local state or pinning.
Opinionated Takeaway: Virtual threads aren’t magic pixie dust. If your code relies heavily on
synchronizedblocks, turning them on might actually degrade performance. Profile before you celebrate.
BAD — Using synchronized on a virtual-thread-hostile path
@Service
public class CacheService {
// This is a problem with virtual threads:
// 'synchronized' pins the virtual thread to its carrier (platform) thread.
// Under high concurrency this creates a bottleneck identical to platform-thread exhaustion.
public synchronized String getOrLoad(String cacheKey) {
if (localCache.containsKey(cacheKey)) {
return localCache.get(cacheKey);
}
// Simulated remote I/O — blocks while pinned to the carrier thread
String fetchedValue = remoteDataSource.fetch(cacheKey);
localCache.put(cacheKey, fetchedValue);
return fetchedValue;
}
private final Map<String, String> localCache = new HashMap<>();
private final RemoteDataSource remoteDataSource;
public CacheService(RemoteDataSource remoteDataSource) {
this.remoteDataSource = remoteDataSource;
}
}IMPROVED — Using ReentrantLock instead of synchronized
import java.util.concurrent.locks.ReentrantLock;
import java.util.concurrent.ConcurrentHashMap;
@Service
public class CacheService {
// ReentrantLock does NOT pin virtual threads to their carrier threads.
// When a virtual thread blocks on lock.lock(), it unmounts from the carrier,
// freeing the carrier to run other virtual threads. This is the key distinction.
private final ReentrantLock cacheLock = new ReentrantLock();
private final Map<String, String> localCache = new ConcurrentHashMap<>();
private final RemoteDataSource remoteDataSource;
public CacheService(RemoteDataSource remoteDataSource) {
this.remoteDataSource = remoteDataSource;
}
public String getOrLoad(String cacheKey) {
cacheLock.lock();
try {
if (localCache.containsKey(cacheKey)) {
return localCache.get(cacheKey);
}
// Virtual thread safely unmounts during this blocking I/O call
String fetchedValue = remoteDataSource.fetch(cacheKey);
localCache.put(cacheKey, fetchedValue);
return fetchedValue;
} finally {
cacheLock.unlock();
}
}
}The JVM’s -Djdk.tracePinnedThreads=full flag is your friend here. Add it to your local startup and watch for pinning warnings before you find out the hard way in production.
Breaking Change #3 — Spring Security Configuration Overhaul
This is where most teams hit the wall. Spring Security’s method-chaining approach for HttpSecurity configuration was soft-deprecated in Boot 3 and is completely removed in Boot 4. Only the lambda DSL — introduced in Spring Security 5.2 — is supported.
The exact compiler error you get when method chaining is still present looks like this:
SecurityConfig.java:18: error: cannot find symbol
.authorizeHttpRequests()
^
symbol: method authorizeHttpRequests()
location: variable httpSecurity of type HttpSecurity
SecurityConfig.java:22: error: cannot find symbol
.and()
^
symbol: method and()
location: class ExpressionInterceptUrlRegistry
2 errors.and() method is gone entirely — not just deprecated. Every occurrence in your codebase is a compile blocker.
BAD — Method chaining (does not compile in Boot 4)
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity httpSecurity) throws Exception {
// This method-chaining style is REMOVED in Spring Boot 4 / Spring Security 7.
// It causes a compilation error — not just a runtime warning.
httpSecurity
.authorizeHttpRequests()
.requestMatchers("/api/public/**").permitAll()
.anyRequest().authenticated()
.and()
.httpBasic()
.and()
.csrf().disable();
return httpSecurity.build();
}
}IMPROVED — Lambda DSL (Boot 4 compatible)
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
public SecurityFilterChain filterChain(HttpSecurity httpSecurity) throws Exception {
// Lambda DSL is the only supported style in Spring Boot 4.
// Each customizer receives a typed config object — no more .and() chaining.
// Benefit: each block configures exactly one concern, reducing scope confusion.
httpSecurity
.authorizeHttpRequests(authorizationConfig ->
authorizationConfig
.requestMatchers("/api/public/**").permitAll()
.anyRequest().authenticated()
)
.httpBasic(httpBasicConfig ->
httpBasicConfig.realmName("MyApp API")
)
.csrf(csrfConfig ->
csrfConfig.disable() // Explicit disable — you must now justify this intentionally
);
return httpSecurity.build();
}
}Why is the lambda DSL better? It’s structurally cleaner. Each lambda gets a strongly typed configuration object, removing scope ambiguity.
Opinionated Takeaway: The lambda DSL is objectively superior. The old method chaining was a nesting nightmare that caused real security holes because developers lost track of which
.and()they were chained to.
Breaking Change #4 — Auto-Configuration Loading Mechanism
Spring Boot 3 moved auto-configuration registration from META-INF/spring.factories to META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports. Boot 4 completes this transition by removing spring.factories support for auto-configuration entirely. Custom starters or internal libraries still using the old mechanism will silently fail to register their beans — no exception, no warning, just missing functionality at runtime.
BAD — Legacy spring.factories (silently ignored in Boot 4)
# META-INF/spring.factories
# This file is IGNORED for auto-configuration in Spring Boot 4.
# CustomDataSourceAutoConfiguration will never be loaded — no error, no warning.
org.springframework.boot.autoconfigure.EnableAutoConfiguration=com.example.infrastructure.CustomDataSourceAutoConfiguration,com.example.monitoring.MetricsAutoConfigurationIMPROVED — AutoConfiguration.imports (Boot 3.x and Boot 4 compatible)
# META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
# One fully-qualified class name per line. No backslash continuation needed.
# This format works for both Boot 3.x and Boot 4 — safe to migrate now.
com.example.infrastructure.CustomDataSourceAutoConfiguration
com.example.monitoring.MetricsAutoConfigurationAt scale, this hurts. A library that worked fine on Boot 3.1 can quietly stop registering on Boot 4. The consuming application starts, but critical infrastructure beans are completely missing. Audit every custom starter.
Here’s the exact stack trace you’ll see in production when a downstream service forgets to migrate its spring.factories. It’s not a compile error—it’s a runtime explosion:
***************************
APPLICATION FAILED TO START
***************************
Description:
Parameter 0 of constructor in com.example.PaymentService required a bean of type 'com.example.infrastructure.CustomDataSource' that could not be found.
Action:
Consider defining a bean of type 'com.example.infrastructure.CustomDataSource' in your configuration.Opinionated Takeaway:
spring.factorieswas basically magic string typing anyway. Good riddance.
Breaking Change #5 — Observation API and Micrometer 2.x
Boot 4 standardizes on Micrometer 2.x and the Observation API. Code directly wiring legacy MetricsRegistry or old Spring Cloud Sleuth hooks will fail at startup. The replacement is a unified ObservationRegistry for metrics, tracing, and logging correlation.
Opinionated Takeaway: Stop building custom metrics wrappers. The new Observation API is finally good enough to use directly without hiding it behind an internal abstraction layer.
BAD — Direct MeterRegistry usage for manual timers
@Service
public class OrderProcessingService {
// Directly injecting MeterRegistry works but bypasses the Observation abstraction.
// In Boot 4, tracing context is NOT automatically propagated —
// your Zipkin/Jaeger spans won't include this timing data.
private final MeterRegistry meterRegistry;
public OrderProcessingService(MeterRegistry meterRegistry) {
this.meterRegistry = meterRegistry;
}
public Order processOrder(OrderRequest orderRequest) {
Timer.Sample timerSample = Timer.start(meterRegistry);
try {
Order processedOrder = doProcessing(orderRequest);
timerSample.stop(meterRegistry.timer("order.processing.time", "status", "success"));
return processedOrder;
} catch (Exception exception) {
timerSample.stop(meterRegistry.timer("order.processing.time", "status", "error"));
throw exception;
}
}
}IMPROVED — Observation API (unified metrics + tracing)
import io.micrometer.observation.Observation;
import io.micrometer.observation.ObservationRegistry;
@Service
public class OrderProcessingService {
// ObservationRegistry is the Boot 4 / Micrometer 2.x unified entry point.
// A single observation automatically creates:
// - A Micrometer timer (metrics)
// - A distributed trace span (if a Brave/OTel bridge is present)
// - Correlated log entries via MDC (if configured)
private final ObservationRegistry observationRegistry;
public OrderProcessingService(ObservationRegistry observationRegistry) {
this.observationRegistry = observationRegistry;
}
public Order processOrder(OrderRequest orderRequest) {
return Observation.createNotStarted("order.processing", observationRegistry)
.lowCardinalityKeyValue("order.type", orderRequest.getType())
.observe(() -> doProcessing(orderRequest));
// On error, the observation automatically records the exception
// and marks the span as failed — no catch block needed for instrumentation.
}
}What Actually Surprised Me Most About This Migration
I expected the Security rewrite to be the hardest part. It wasn’t — IntelliJ’s quick-fix for the lambda DSL conversion is actually good, and the new API is cleaner once you’ve written it once. What I genuinely did not anticipate was how many internal libraries and shared starters my team maintained were still pointing at spring.factories. Three of them. In three different Git repos. None of them raised a compile error — they just silently stopped registering their auto-configuration beans, which showed up as a NoSuchBeanDefinitionException for a completely unrelated class that happened to depend on one of those beans. Chasing that failure took most of a day.
The second surprise: virtual threads being on by default surfaced a pinning issue in a legacy encryption utility that had been in production for four years without incident. The bug was always there — it just never mattered until carrier threads started getting starved under concurrent load. The lesson is that enabling virtual threads is not free validation of your existing concurrency model. It’s a stress test of assumptions you’ve never had to defend before.
What Most Tutorials Don’t Tell You
1. Deprecated API Cleanup Must Happen Before the Version Bump
Every tutorial says “upgrade to Boot 4.” None of them say: your Boot 4 build will fail to compile if you have un-addressed deprecated API usages from Boot 3.x. The Spring team is thorough — deprecated methods are removed, not just suppressed. The correct migration path is:
- Upgrade to the latest Boot 3.x minor (e.g., 3.4.x).
- Enable deprecation-as-error in your build (
-Werrorin javac orfailOnWarning=truein Maven Compiler). - Fix every deprecation warning.
- Then bump to Boot 4.
Skipping steps 2 and 3 means you’ll hit a wall of compilation errors on Boot 4 with no clear map of what needs changing. Teams that follow this process report that the actual Boot 4 version bump becomes a one-day task rather than a two-week scramble.
2. ThreadLocal Usage Becomes a Silent Data Leak
With virtual threads enabled by default, ThreadLocal variables are still supported but behave dangerously in thread-pool scenarios. A ThreadLocal value set on a virtual thread may persist longer than expected if the framework reuses the underlying carrier thread. In production systems with request-scoped security context propagation, this can cause context bleed between requests.
# application.properties
# Spring Security uses ThreadLocal for SecurityContextHolder by default.
# With virtual threads, switch to InheritableThreadLocal mode OR
# configure explicit propagation. Boot 4 sets the correct default,
# but custom ThreadLocal usage in your own code is your responsibility.
# VirtualThread-safe strategy for SecurityContextHolder:
spring.security.strategy=MODE_INHERITABLETHREADLOCAL
# Longer term: replace ThreadLocal with ScopedValue (Java 21 preview / Java 23 standard).3. Your Health Checks May Return Wrong Status
Boot 4’s Actuator health endpoint refactors how composite health indicators aggregate status. If you have custom HealthIndicator beans with specific ordering dependencies, the aggregation order is no longer guaranteed by registration order — it’s now controlled by @Order annotations and a new HealthEndpointGroup configuration. In Kubernetes deployments, a misconfigured liveness probe that returns UP when the application is actually unhealthy can block pod restarts and cause silent downtime.
Under the Hood: How Auto-Configuration Actually Loads in Boot 4
When your Spring Boot 4 application starts, SpringApplication.run() triggers a chain of events that’s worth understanding if you want to debug startup failures quickly:
- SpringFactoriesLoader is invoked — but in Boot 4 it no longer reads the
EnableAutoConfigurationkey fromspring.factories. It still reads other keys (likeApplicationListenerorEnvironmentPostProcessor), sospring.factoriesisn’t dead — it just no longer loads auto-configuration classes. - AutoConfigurationImportSelector reads AutoConfiguration.imports — this file is loaded from each JAR on the classpath. One malformed line (wrong class name, wrong package) causes a
ClassNotFoundExceptionat startup that can be hard to trace if you have many starters. - @Conditional evaluation runs — each auto-configuration class is evaluated against its
@ConditionalOnClass,@ConditionalOnMissingBean, etc. In Boot 4, the AOT engine pre-computes these conditions at build time for GraalVM native images — dynamic conditional logic that worked fine in JVM mode may silently not register beans in native mode. - Virtual thread executor is registered — before the servlet container starts, Boot 4 registers a
VirtualThreadTaskExecutoras the Tomcat/Undertow/Jetty thread executor. This happens before your application beans are initialized, so any bean that assumes platform-thread semantics at startup is already running on virtual threads.
To debug startup issues, use the --debug flag or set logging.level.org.springframework.boot.autoconfigure=DEBUG. Boot 4 prints a detailed auto-configuration report showing exactly which conditions passed or failed for each class.
Common Mistakes During Spring Boot 3 to 4 Migration
- Bumping the parent version without auditing transitive dependencies. Your application pom.xml may look clean, but a single outdated internal library using
spring.factoriessilently drops its auto-configuration. - Assuming tests cover concurrency behavior. Most unit and integration tests run single-threaded. Virtual thread bugs (pinning, ThreadLocal bleed) only surface under concurrent load. Add load tests to your migration validation pipeline.
- Forgetting to update Dockerfile/CI base images. Your code compiles on Java 21 locally, but the CI agent still runs JDK 17. The build passes in dev and fails in the pipeline.
- Leaving
@EnableSchedulingwithout reviewing task executor wiring. In Boot 4, scheduled tasks may now run on virtual threads depending on your executor configuration. Scheduled jobs with synchronized internals can exhibit the pinning issue described above. - Not testing Spring Data JPA behavior. Spring Data 4.x changes lazy loading behavior for certain proxy configurations. N+1 query issues that were hidden by eager loading in previous versions may now surface.
Best Practices for a Smooth Spring Boot 3 to 4 Migration
- Create a migration branch per service — don’t attempt to migrate a multi-module monorepo in one PR. Smaller scope means faster review and easier rollback.
- Run the Spring Boot Migration Assistant — the official OpenRewrite recipe (
org.openrewrite.java.spring.boot3.UpgradeSpringBoot_4_0) automates a large portion of the mechanical changes. It won’t catch everything, but it eliminates the busywork. - Pin third-party library versions explicitly — don’t rely on Boot 4’s BOM to resolve a compatible version of libraries your team doesn’t control. Verify compatibility manually and pin.
- Enable
-Djdk.tracePinnedThreads=fullin staging — run your full regression suite with this JVM flag to identify everysynchronizedblock that will pin virtual threads. Fix before going to production. - Validate Actuator endpoints after migration — hit
/actuator/health,/actuator/metrics, and/actuator/infoand verify the response structure. Boot 4 changes some payload shapes. - Keep Boot 3.x in production until Boot 4 completes a full staging soak test — at minimum 72 hours of production-equivalent traffic through the new version before cutting over.
A Quick War Story: Migrating a Payment Gateway
To give you an idea of what this looks like in practice, here’s a recent migration of a payment gateway handling ~8,000 requests/second at peak (Spring Boot 3.1, Java 17, Spring Security for JWTs, and Micrometer + Zipkin for observability):
Week 1 — Deprecation audit on Boot 3.4.x. The Maven compiler deprecation-as-error flag surfaced 23 deprecated usages. Eighteen were in the team’s own code (mostly old HttpSecurity chaining). Five were in an internal auth-library that hadn’t been updated in 18 months. The library was updated and re-published before the Boot 4 bump began.
Week 2 — Boot 4 version bump and build failure resolution. The build itself failed once — the internal metrics library still used spring.factories for its MetricsAutoConfiguration. After migrating it to AutoConfiguration.imports, the build succeeded. Startup time was actually faster: virtual threads reduced Tomcat’s startup cost by approximately 15% due to lower OS thread creation overhead.
Week 3 — Staging load test. With -Djdk.tracePinnedThreads=full enabled, the team found two synchronized blocks in a legacy encryption utility being pinned under concurrent load. Replacing them with ReentrantLock eliminated the warnings. Throughput in staging improved from ~8,200 req/s to ~11,400 req/s — a 39% gain attributable almost entirely to virtual threads removing platform-thread contention on I/O waits to the payment processor API.
Week 4 — Production cutover. Zero incidents. The observability payloads from Micrometer 2.x were richer (unified span + metric correlation), which actually improved the team’s on-call experience.
A Few LLM Prompts That Can Help
If you’re using an AI assistant (Claude, ChatGPT, Copilot, etc.), these prompts can save you a ton of time during the migration:
- “Scan this Spring Boot service’s pom.xml and list all dependencies that might not have Spring Boot 4 compatible versions yet.”
- “Convert this HttpSecurity method-chaining configuration to the Boot 4 lambda DSL. Preserve all existing rules and explain each change.”
- “Find all uses of synchronized blocks in this codebase that could cause virtual thread pinning, and suggest ReentrantLock replacements.”
- “Review this spring.factories file and generate the equivalent AutoConfiguration.imports content for Spring Boot 4.”
- “This code uses MeterRegistry directly. Refactor it to use the Micrometer ObservationRegistry API for Boot 4 compatibility.”
What to Actually Do This Week
Migrating from Spring Boot 3 to 4 isn’t just a “bump the version and fix the red squigglies” exercise. The changes touch your concurrency model, security wiring, observability stack, and configuration loading. But if you do it carefully, the payoff is huge — virtual threads alone can massively improve throughput for I/O-bound services without you touching a single line of business logic.
Here are your actionable steps for this week:
- Upgrade your current service to the latest Boot 3.x and enable deprecation-as-error. Fix everything that surfaces.
- Audit all internal libraries and custom starters for
spring.factoriesusage and migrate them toAutoConfiguration.imports. - Search your codebase for
synchronizedblocks on I/O paths and plan replacements before the Boot 4 bump. - Verify your CI pipeline and production Docker images are JDK 21 compatible.
- Run the OpenRewrite Boot 4 recipe on a feature branch and review the diff before committing.
If you treat this migration as just another dependency update, you’re going to have a bad time. Treat it as a runtime model upgrade — because that’s exactly what it is.