How to migrate your application to Spring Boot 3.0


Spring Boot has revolutionized the way modern applications are built. Its opinionated view of the Spring platform and minimal configuration allows developers to quickly build robust enterprise-grade applications. Spring Boot 3.0 was officially released in November 2022, and gives us many new features and improvements. Based on version 6.0 of the Spring Framework, Spring Boot 3.0 includes advanced observability, GraalVM Native Image support, a Java 17 baseline with new language features, and JVM/garbage collector performance improvements. With Spring Boot 2.x support ending at the close of 2023, it’s time to upgrade. In this article we’ll take a look at the process of upgrading from Spring Boot 2 to Spring Boot 3, and provide some special considerations, best practices, and recommendations for ensuring a smooth and seamless upgrade.

Migration Strategy

The migration to Spring Boot 3.0 requires a series of associated migrations and dependency updates, both possible sources of friction. Taking a methodical approach will help the process go smoothly. The Spring Boot Team recommends first incrementally upgrading your application to the latest Spring Boot 2.7.x version (e.g. 2.5 -> 2.6 -> 2.7). This helps reduce complexity by letting you resolve any api changes/depreciations that were made in minor version upgrades step by step before making the jump to 3.0. It’s also recommended that you update your Spring Security version to 5.8 before upgrading, the Spring Security team released this version to help simplify the upgrade to Spring Security 6.0.  

Next you’ll want to update your Java version to JDK 17 in your build file. As of Java 9, many J2EE javax dependencies have been removed from the core JDK (e.g. Jackson, Hibernate). If using these libraries in your application you’ll need to add them as explicit dependencies to your project’s build file. Another major change is the migration of the J2EE libraries to Jakarta. This changes the namespace of these libraries from javax.* to jakarta.* For example, the package of the commonly used javax persistence library changes from javax.persistence to jakarta.persistence. This change will require fixing some imports, which can usually be as simple as a search & replace. This should be done carefully however, as some javax libraries still exist in the javax namespace in JDK 17 (e.g. javax.sql). IntelliJ also provides a refactor tool to assist with this.

Upgrade to the latest available maintenance release of Spring Boot 3.0 in your build file. Carefully review and upgrade any dependencies not managed by Spring as needed, making sure each project has Jakarta EE9 & Spring 6 compatible releases. For example, Enfuse uses Spring Cloud for many of our microservices and we found that we needed to update to the Spring Boot 3/Spring 6.0 compatible release train (2022.0.x). Check carefully and update dependencies in your build file as necessary. 

After updating dependencies you’ll likely see some compile errors. API changes, depreciations and removals in newer versions of third party libraries may require updating your application code. As an example, a common pattern for configuring security has been to inherit the Spring WebSecurityConfigurerAdapter class. This has been removed in Spring Security 6 in favor of configuring a SecurityFilterChain Bean. Another change is the .antMatchers() method of authorizeRequest has been renamed to .requestMatchers(). Review each issue and fix as necessary. Refer to the official Spring Boot 3 migration guide for details & suggested fixes for known breaking changes you may find in your code if using certain Spring managed dependencies.

Several configuration properties have been renamed/removed in Spring Boot 3.0, which may require you to make some changes in your application properties. Spring provides a spring-boot-properties-migrator module to help migrate your configuration to Boot 3.0. This can be added as a dependency to your project’s build file, and will analyze your application’s environment and print diagnostics at startup (make sure to remove this when Spring Boot migration is complete).

To assist with the process of upgrading to Spring Boot 3.0, the Spring team has provided Spring Boot Migrator (SBM), a utility that can automate the process of upgrading your Spring 2.7 application to Spring Boot 3.0. Spring Boot Migrator provides a CLI to run various “recipes”, one of which will upgrade an existing Spring Application to version 3.0. Please note that Gradle based projects are not supported at this time, SBM currently supports only Maven projects using Spring Boot version 2.7 and Java 17.


In most cases, the upgrade to Spring Boot 3.0 will be a fairly straightforward process. In addition to this guide, we recommend carefully reviewing the official Spring 3.0 migration guide to familiarize yourself with up to date upgrade instructions from the Spring Team. For maven projects, leverage the Spring Boot Migrator tool to automate the upgrade process. Using these resources, put a plan together that can serve as a guide while upgrading your Spring Boot applications up to 3.0. Following these steps, you will be able to take advantage of all the improvements & new features Spring Boot 3 & Java 17 have to offer. If you require more help, our team at Enfuse.io would love to help you migrate your apps. Reach out to us at info@enfuse.io.


Official Spring Boot 3.0 migration guide: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Migration-Guide

Spring Boot 3.0 Release Notes: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Release-Notes

Spring Boot Migrator (Maven only): https://github.com/spring-projects-experimental/spring-boot-migrator#try-the-spring-boot-upgrade-tool

Spring Boot Configuration Properties Migration: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Migration-Guide#configuration-properties-migration

Changes made Spring Boot 3.0 Configuration : https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-3.0-Configuration-Changelog

Spring Boot 3.0 managed dependency versions: https://docs.spring.io/spring-boot/docs/3.0.x/reference/html/dependency-versions.html#appendix.dependency-versions

New Java Language Features from version 9 through 17: https://blogs.oracle.com/javamagazine/post/java-eckel-index


Tom Butler