Spring Boot 4.0 Is Coming, and Your 3.x Apps Won't Just Recompile

Most major version bumps in the Spring ecosystem are manageable. You read the release notes, bump a few dependencies, fix what the compiler complains about, and move on. Spring Boot 4.0 is not that kind of release.

The jump from 3.5 to 4.0 carries 115 distinct breaking changes, and they don't all announce themselves. Some stop your build. Some let the build pass and then fail at runtime. And a smaller, more dangerous set lets the application compile, start, and run while quietly returning the wrong results. Steve Poole, a longtime Java Champion, developer advocate, software engineer, author, and speaker, has cataloged all of them in a free Spring Boot 4.0 Migration Guide sponsored by HeroDevs. It is the clearest map we've seen of what this migration actually involves.

Three tiers of breakage

The guide's most useful decision is how it sorts the changes. Instead of one long list, it groups them by how they fail.

Tier 1, won't build. These are the 42 changes that stop compilation. Gradle 8.14 or 9 is now required. The AOP starter was renamed. Undertow as an embedded server is gone. OkHttp3 support was removed. Spring Security got a DSL rewrite, and a long list of classes moved packages. This tier is the loudest one. Your build breaks, you know immediately, and you fix it.

Tier 2, won't run. These 24 changes pass the build and then fail when the application starts or executes. The javax.annotation and javax.inject namespaces are no longer recognized. RestTemplate auto-configuration was removed. The OAuth 2.0 password grant is gone entirely. @MockBean and @SpyBean were removed from the test framework. These are harder, because a green build gives you false confidence right up until something tries to run.

Tier 3, wrong results. This is the tier that should worry you most, and it's the reason a migration like this needs real planning rather than a weekend. These 19 changes build cleanly, run without error, and produce different output than before. Jackson's date serialization defaults flipped. MongoDB's default UUID representation changed. Logback's default charset moved to UTF-8. Liveness and readiness probes are now enabled by default. None of these throw. They just behave differently, and you find out in production unless you're looking for them.

What's driving the churn

A few large shifts account for most of the list. Jackson 3.0 brings class renames, a group ID change, new serialization defaults, and module auto-discovery, and it touches dozens of cards on its own. The long-running migration away from the javax namespace reaches its conclusion. Hibernate 7 removes a set of long-deprecated APIs and changes query behavior. Spring Security's access APIs relocated and its DSL was rewritten. And the build floor moved up, with Gradle 9 and GraalVM 25 now required for native images.

Individually, most of these are tractable. Together, across an application with real dependency depth, they add up to a migration that the guide treats seriously enough to include its own impact and sizing estimates.

OpenRewrite helps, but it doesn't think for you

Eighteen of the 115 cards ship with OpenRewrite recipes, which means a meaningful share of the mechanical edits can be automated. That's worth using. But automation handles the renames and relocations, not the judgment calls. The Tier 3 behavior changes in particular require someone to understand what the old default was doing, decide whether the new one is acceptable, and test for the difference. Tooling accelerates the edits. It does not make the decisions.

The deadline underneath all of this

There's a clock on this work. Spring Boot 3.5 effectively reaches open-source end of life on June 30, 2026. After that date, the community stops shipping security patches for the 3.x line. Teams now face two pressures at once: a substantial migration to plan and a support window that's closing.

For most teams, the right move is to scope the 4.0 migration now, while there's runway. For teams that can't realistically finish before the end-of-life date, there's a bridge. Never-Ending Support for Spring keeps your current version patched and compliant after upstream support ends, so the migration happens on your timeline instead of against the June 30 deadline. Either way, the first step is knowing the scope.

Start with the map

Steve Poole's guide is the fastest way to understand what your specific applications are in for. It breaks the migration into the three tiers above, flags which changes have automated recipes, and organizes the same content by technology so you can jump straight to the parts that affect your stack.

Download the Spring Boot 4.0 Migration Guide.

The guide was written by Steve Poole and is sponsored by HeroDevs as part of our work keeping the Spring ecosystem secure and supported well past end of life.