Spring Boot 2 → 3 migration: what the official guide does not tell you
Spring Boot 3 has been GA since November 2022 and most teams have not migrated. The reasons are familiar: javax → jakarta namespace migration touches every package import, the Spring Security DSL changed substantially, half your dependencies are still on Spring Boot 2 and the maintainers have gone quiet. We have completed this migration on fourteen production codebases since 2023, including one banking platform with 380,000 lines of Java. The official upgrade guide is honest but incomplete — here is what we hit in practice that is not documented.
The Jakarta migration is the easy part. The mechanical javax → jakarta package rename is well-tooled — OpenRewrite has recipes that handle 95% of cases, and the remaining 5% are almost always cases where you have an import declared in a comment or a string literal. The real friction is in dependencies, not your own code. Expect 8-15 of your transitive dependencies to need explicit version bumps; expect 2-3 to be unmaintained and require a fork or a replacement.
Spring Security DSL changes are where teams get stuck. The deprecation of WebSecurityConfigurerAdapter in favor of SecurityFilterChain bean wiring is a real refactor in any codebase that customized authorization rules. We see clients spend 2-3 weeks of senior engineer time on this section alone, then discover the test coverage was thin and they cannot tell if behavior changed.
Micrometer 1.10+ observability changes are silent. Spring Boot 3's observability shifted from Spring Cloud Sleuth to Micrometer Tracing. Existing distributed tracing instrumentation continues to compile but produces different span structure. Your dashboards may show data that looks correct but is subtly off in cardinality.
Native image builds with GraalVM are tempting but expensive. Spring Boot 3 added native image support and the demo is impressive. The reality for non-trivial applications: 30-60 minute build times, native-image reflection metadata is a moving target, and library compatibility is patchier than the marketing suggests. For most applications a well-tuned JVM startup with class data sharing is the better choice for the next 18 months.
Our actual migration sequence. Week 1: dependency audit + write the OpenRewrite recipe overrides for your conventions. Week 2: jakarta migration on a feature branch, all-tests-pass gate before merge. Week 3-4: Spring Security DSL refactor with explicit before/after permission tests. Week 5: Micrometer Tracing cutover with dashboard validation. Week 6: production deploy behind a feature flag, observe for 7 days, then commit. This shape has worked on every codebase we have done it on; the variation is which week each phase takes and where the dependency hell appears.
If you are putting this off because the team estimate is 8 weeks: that estimate is probably right. If you are putting it off because someone proposed 2 weeks: that estimate is wrong. Spring Boot 3 migration is not a sprint, but it is also not the rewrite some people fear.