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:

<code>spring:
  config:
    use-legacy-processing: true
</code>

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:

<code>---
spring:
  profiles:
    active: dev
  application:
    name: dev-app
server:
  port: 8081
---
spring:
  profiles:
    active: prod
  application:
    name: prod-app
server:
  port: 8080
</code>

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:

<code>spring:
  profiles: "prod"
secret: "production-password"
</code>

New style:

<code>spring:
  config:
    activate:
      on-profile: "prod"
secret: "production-password"
</code>

The old

spring.profiles.active

can still be used on the command line, e.g.:

<code>$ java -jar myapp.jar --spring.profiles.active=prod
</code>

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:

<code># Invalid configuration
spring:
  config:
    activate:
      on-profile: "prod"
  profiles:
    include: "metrics"
</code>

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.