Essential Guide to Upgrading Your Spring Boot Apps to 3.0

Spring Boot 3.0 has been officially released, marking the first major revision since 2.0 and supporting Spring Framework 6.0, GraalVM, and Java 17 with Jakarta EE 9/10.

3.0 Upgrade Guide

If you want to try Spring Boot 3.0, follow this upgrade guide.

Upgrade JDK

Upgrade your JDK to JDK 17. For Native Image support, use GraalVM 22.3+ and Native Build Tools Plugin 0.9.17 or higher.

Smooth Upgrade Path

Avoid jumping directly from versions earlier than 2.7 to 3.0. Instead, upgrade stepwise through 2.4, 2.6, 2.7 before moving to 3.0.

Dependency Assessment

Check version requirements of dependencies such as Spring Boot Kafka Starter and upgrade Spring Cloud after the Spring Boot 3.0 release.

Upgrade to Spring Boot 3

After preparation, you can start upgrading to Spring Boot 3.0.

Configuration Property Compatibility

Some configuration properties have been renamed or removed. Update application.properties or application.yml. Add the spring-boot-properties-migrator module as a runtime dependency to help migrate properties.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-properties-migrator</artifactId>
  <scope>runtime</scope>
</dependency>

After migration, be sure to remove the spring-boot-properties-migrator dependency.

Jakarta EE

Package names changed from javax to jakarta. Use IntelliJ IDEA 2021.2’s built‑in refactoring to batch rename.

Key Changes

Various important changes affect most applications.

Banner Images No Longer Supported

Custom banners now only support text files ( banner.txt), not images.

Log Date Format Change

Logback and Log4j2 default to ISO‑8601 format yyyy-MM-dd'T'HH:mm:ss.SSSXXX. Use LOG_DATEFORMAT_PATTERN or logging.pattern.dateformat to revert to the old format.

@ConfigurationProperties Annotation

The @ConstructorBinding annotation is no longer required unless multiple constructors are present.

YamlJsonParser Removed

Due to inconsistencies, replace YamlJsonParser with other JsonParser implementations.

Auto‑configuration File Change

Spring Boot 2.7 introduced

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

. The old spring.factories file is removed; use the new imports file.

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

Web Changes

Path Matching

Trailing slash handling has changed; /foo/bar and /foo/bar/ are no longer equivalent.

Deprecated server.max-http-header-size

Replace with server.max-http-request-header-size. To limit response header size, customize WebServerFactoryCustomizer.

Graceful Shutdown Phase Changes

SmartLifecycle phases have shifted; update implementations accordingly.

Jetty

Jetty does not yet support Servlet 6.0, so use Jakarta Servlet 5.0.

Data Access Changes

Properties under spring.data are reserved; rename spring.redis to spring.data.redis. Updated component versions: Flyway 9.0, Hibernate 6.1, R2DBC 1.0.

MongoDB

Embedded MongoDB auto‑configuration has been removed; add it manually if needed.

Elasticsearch

The Rest client now uses a new API; old auto‑configuration and client API are removed.

Spring Security

Further changes will be documented separately.

Other Changes

Observability, metrics, Maven, Gradle, and other areas also have updates; refer to the official Spring Boot 3.0 Migration Guide for details.