How to Seamlessly Migrate Your Spring Boot Apps to 3.0 – A Practical Guide

Spring Boot entered its 2.0 era on February 28 2018, and after more than four years Spring Boot 3.0 is slated for release in November 2022. It will be based on Spring Framework 6.0, require Java 17 or higher, and be the first Spring Boot version built for Jakarta EE 9. You have roughly six months to prepare for the migration.

Java 17

Java 17 is the most important LTS release since Java 8, bringing many performance and language improvements. All Spring Boot 2.x versions already run well on Java 17, so you can start upgrading your JDK and experimenting with new features immediately.

Upgrade to Spring Boot 2.7 First

Spring Boot 2.7 is the last major 2.x release. Earlier versions (2.5, 2.6) are already out of OSS support or will be discontinued after Spring Boot 3.0 launches. Upgrade incrementally (2.4 → 2.5 → 2.6 → 2.7) rather than jumping directly to avoid migration pain.

Remove Deprecated Code

Each Spring Boot release marks some APIs with @Deprecated. Spring Boot 3.0 will completely drop code deprecated in the 2.x line, so eliminate usage of deprecated elements now; they usually include comments pointing to replacement APIs.

Configuration File Changes

Starting with Spring Boot 2.4, the loading mechanism for application.properties and application.yaml changed, breaking backward compatibility. A legacy‑processing flag can ease the transition:

spring:
  config:
    use-legacy-processing: true

This flag will be removed in 3.0, so you must adopt the new configuration style.

Multi‑Document YAML

If you use the --- separator to declare multiple documents in a YAML file, the order of registration now follows the document order, whereas older versions relied on spring.profiles.active activation order. Example:

---
spring:
  profiles:
    active: dev
  application:
    name: dev-app
server:
  port: 8081
---
spring:
  profiles:
    active: prod
  application:
    name: prod-app
server:
  port: 8080

From 2.4 onward, later properties overwrite earlier ones.

External Configuration Always Overrides JAR‑Embedded Files

When a configuration file exists outside the JAR (e.g., application‑dev.yaml), versions prior to 2.4 did not let an external application.yaml override application‑<profile>.yaml inside the JAR. From 2.4 onward, external files always take precedence, so verify that you are not unintentionally overriding settings.

Activating Profiles

If you previously used spring.profiles to activate environments, migrate to the new spring.config.activate.on-profile property. Old style:

spring:
  profiles: "prod"
secret: "production-password"

New style:

spring:
  config:
    activate:
      on-profile: "prod"
secret: "production-password"

The old spring.profiles.active can still be used on the command line, e.g.:

$ java -jar myapp.jar --spring.profiles.active=prod

However, it can no longer be used inside application‑<profile>.yaml or multi‑document YAML files after 2.4.

Invalid Use of spring.profiles.include

The spring.profiles.include attribute is only valid in non‑specific configuration files. The following is invalid:

# Invalid configuration
spring:
  config:
    activate:
      on-profile: "prod"
  profiles:
    include: "metrics"

Higher‑Performance Path Matching

From Spring Boot 2.6, the default path matcher switched from AntPathMatcher to PathPatternParser, which offers better performance. Some users experienced Swagger issues; setting spring.mvc.pathmatch.matching-strategy to ant_path_matcher resolves them. Although AntPathMatcher remains supported in 3.0, PathPatternParser is the recommended approach.

Compatibility Concerns

Ensure that third‑party libraries and your codebase are compatible with Jakarta EE 9, and verify that any Spring Framework dependencies you rely on have plans to support Spring 6.

Start Exploring Spring 6

Spring 6 and Spring Boot 3 have introduced many milestones. Take some time to experiment with the new features and assess the effort required to upgrade your applications.