Migrate Spring Boot 2.x applications to Spring Boot 3.x. Use when updating pom.xml versions, removing deprecated JAXB dependencies, upgrading Java to 17/21, or using OpenRewrite for automated migration. Covers dependency updates, version changes, and migration checklist.
This skill provides guidance for migrating Spring Boot applications from version 2.x to 3.x, which is one of the most significant upgrades in Spring Boot history due to the Java EE to Jakarta EE transition.
Change the parent POM version:
<!-- Before: Spring Boot 2.7.x -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.7.18</version>
</parent>
<!-- After: Spring Boot 3.2.x -->
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.2.0</version>
</parent>
Spring Boot 3 requires Java 17 or later:
<properties>
<!-- Before -->
<java.version>1.8</java.version>
<!-- After -->
<java.version>21</java.version>
</properties>
You MUST remove the old javax.xml.bind:jaxb-api dependency. This is a Java EE dependency that was commonly added for Java 9+ compatibility in Spring Boot 2.x projects, but it conflicts with Jakarta EE in Spring Boot 3.
<!-- REMOVE ALL OF THESE - they are incompatible with Spring Boot 3 -->
<!-- Old JAXB API - MUST BE REMOVED -->
<dependency>
<groupId>javax.xml.bind</groupId>
<artifactId>jaxb-api</artifactId>
</dependency>
<!-- Old JAXB Implementation - MUST BE REMOVED -->
<dependency>
<groupId>com.sun.xml.bind</groupId>
<artifactId>jaxb-impl</artifactId>
</dependency>
<dependency>
<groupId>com.sun.xml.bind</groupId>
<artifactId>jaxb-core</artifactId>
</dependency>
<!-- Old Java Activation - MUST BE REMOVED -->
<dependency>
<groupId>javax.activation</groupId>
<artifactId>activation</artifactId>
</dependency>
<dependency>
<groupId>javax.activation</groupId>
<artifactId>javax.activation-api</artifactId>
</dependency>
javax.xml.bind uses the old Java EE namespace, which conflicts with Jakarta EE's jakarta.xml.bindjavax.xml.bind and jakarta.xml.bind on the classpath causes ClassNotFoundException and other runtime errorsUse the Jakarta versions instead:
<!-- Only add these if you actually need XML binding -->
<dependency>
<groupId>jakarta.xml.bind</groupId>
<artifactId>jakarta.xml.bind-api</artifactId>
</dependency>
<dependency>
<groupId>org.glassfish.jaxb</groupId>
<artifactId>jaxb-runtime</artifactId>
</dependency>
# Check if old JAXB is in your pom.xml
grep -E "javax\.xml\.bind|jaxb-api" pom.xml
# If this returns any results, you need to remove those dependencies
After removing, confirm no old JAXB references remain:
# This should return NO results
grep -E "<artifactId>jaxb-api</artifactId>" pom.xml
grep -E "javax\.xml\.bind" pom.xml
The old jjwt library needs to be replaced with the newer modular version:
<!-- Before -->
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt</artifactId>
<version>0.9.1</version>
</dependency>
<!-- After -->
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-api</artifactId>
<version>0.12.3</version>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-impl</artifactId>
<version>0.12.3</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>io.jsonwebtoken</groupId>
<artifactId>jjwt-jackson</artifactId>
<version>0.12.3</version>
<scope>runtime</scope>
</dependency>
After changing the Spring Boot version, you'll see many compilation errors related to javax.* imports. These need to be changed to jakarta.* (see Jakarta Namespace skill).
The H2 dialect class name changed:
# Before
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
# After
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
# Note: In Hibernate 6, this is often auto-detected and may not need explicit configuration
Actuator endpoint paths have changed. Review your security configuration if you're exposing actuator endpoints.
# Update Spring Boot parent version
sed -i 's/<version>2\.7\.[0-9]*<\/version>/<version>3.2.0<\/version>/g' pom.xml
# Update Java version
sed -i 's/<java.version>1\.8<\/java.version>/<java.version>21<\/java.version>/g' pom.xml
sed -i 's/<java.version>8<\/java.version>/<java.version>21<\/java.version>/g' pom.xml
sed -i 's/<java.version>11<\/java.version>/<java.version>21<\/java.version>/g' pom.xml
# Remove old JAXB dependency (multi-line removal is complex - manual removal recommended)
# Check for old JAXB dependencies
grep -n "jaxb-api\|javax\.xml\.bind" pom.xml
# These must be manually removed from pom.xml:
# - javax.xml.bind:jaxb-api
# - com.sun.xml.bind:jaxb-impl
# - com.sun.xml.bind:jaxb-core
OpenRewrite is the recommended tool for large-scale migrations:
<plugin>
<groupId>org.openrewrite.maven</groupId>
<artifactId>rewrite-maven-plugin</artifactId>
<version>5.42.0</version>
<configuration>
<activeRecipes>
<recipe>org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_2</recipe>
</activeRecipes>
</configuration>
<dependencies>
<dependency>
<groupId>org.openrewrite.recipe</groupId>
<artifactId>rewrite-spring</artifactId>
<version>5.21.0</version>
</dependency>
</dependencies>
</plugin>
mvn rewrite:run
This will automatically:
javax.* to jakarta.* imports# Should show 3.x version
grep -A2 "spring-boot-starter-parent" pom.xml | grep version
# Should show 17 or 21
grep "java.version" pom.xml
# All should return NO results
grep "jaxb-api" pom.xml
grep "javax\.xml\.bind" pom.xml
grep "<version>0\.9\.1</version>" pom.xml # Old jjwt version
# Compile the project
mvn clean compile
# Run tests
mvn test
spring-boot-starter-parent version to 3.2.xjava.version to 17 or 21javax.xml.bind:jaxb-api and related JAXB dependenciesio.jsonwebtoken:jjwt if present, replace with modular jjwtmvn clean compile to identify remaining issuesjavax.* to jakarta.* imports