AutoGineer
Generated banner for Spring Boot 4 Migration
Generated logo for Spring Boot 4 Migration

Spring Boot 4 Migration

GitHubOfficialFirst committed by jduboisDistributed by GitHub

  • Skill
  • Workflow
  • Software development
  • MIT
  • No issues found
Download ZIP

From the author

Migrate a Spring Boot 3.x application to Spring Boot 4.0 (Spring Framework 7, Jackson 3, modular starters, JSpecify). Use only for an explicit Boot 3.x to 4 migration, or to fix build or test failures caused by it, or to review one. Not for 3.x patch bumps or 4.0 to 4.1 upgrades; follow the target Boot version release notes and upgrade guide for those. Covers Maven and Gradle (Kotlin DSL, version catalogs).
— the description by jdubois

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a systematic approach to upgrading Spring Boot applications from version 3.x to 4.0. It covers critical architectural changes, including the shift to Spring Framework 7, Jackson 3, and modular starters. The workflow emphasizes a methodical, incremental migration process—starting with a baseline at the latest 3.5.x version—to ensure build stability and test integrity throughout the transition. It supports both Maven and Gradle (including Kotlin DSL and version catalogs) and provides guidance on handling configuration properties, testing framework updates, and observability modules.

What it does

  • Guides the user through a multi-step migration process from Spring Boot 3.x to 4.0.
  • Provides instructions for updating build configurations in Maven and Gradle.
  • Details the transition to modular starters and Jackson 3.
  • Offers a checklist for verifying build, tests, and runtime health.
  • Includes references for specific migration topics like testing, security, and observability.
  • Suggests using OpenRewrite recipes where available to automate parts of the migration.

When to use it

  • When performing an explicit migration from a Spring Boot 3.x application to 4.0.
  • When troubleshooting build or test failures specifically caused by a 3.x to 4.0 migration.
  • When reviewing a codebase that has undergone a 3.x to 4.0 migration.
  • When you need to identify the correct order of operations for updating dependencies and configuration.

Advantages

  • Promotes a safe, incremental migration strategy that minimizes breaking changes.
  • Provides clear guidance on handling complex changes like Jackson 3 and modular starters.
  • Supports both Maven and Gradle build systems.
  • Includes a final verification checklist to ensure application stability.
  • Directs users to official documentation for deep-dive technical details.

Usage examples

“How do I start migrating my Spring Boot 3.2 application to 4.0?”
The agent will guide you to first upgrade to the latest 3.5.x version, establish a baseline with passing tests, and then proceed with the 4.0 migration steps.
“I am getting build errors after updating to Spring Boot 4.0 regarding Jackson. What should I do?”
The agent will point you to the Jackson 3 migration reference, explaining the package renames and the use of the temporary compatibility module.
“How should I handle the new modular starters in my Gradle build?”
The agent will explain the difference between technology-specific starters and classic starters, providing examples for your libs.versions.toml and build.gradle.kts files.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/github/spring-boot-4-migration/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip spring-boot-4-migration.zip -d .agents/skills

Documentation by jdubois

Spring Boot 3.x to 4.0 Migration

Step-by-step migration workflow. Topic details live in references/; load only the files relevant to the current step.

Rules

  • Never read or print secrets (.env, credentials, tokens in properties files).

  • Change one thing per step and run the test suite after each step; commit nothing you cannot build.

  • Pin versions explicitly; never use latest or open-ended ranges.

  • Check the official sources when unsure: the Spring Boot 4.0 Migration Guide on the Spring Boot GitHub wiki and the release notes on spring.io.

Workflow

  1. Detect the current state

    • Boot version: pom.xml (spring-boot-starter-parent / BOM version), build.gradle(.kts) (org.springframework.boot plugin), or gradle/libs.versions.toml.

    • Build tool: pom.xml + mvnw means Maven; build.gradle.kts / build.gradle means Gradle (Kotlin or Groovy DSL). Use the project wrapper (./mvnw, ./gradlew).

    • Java version (Boot 4 needs Java 17+, Java 25 recommended), Kotlin version, and key libraries (Jackson, Hibernate, Security, Kafka, Elasticsearch, MongoDB).

    • See prerequisites.

  2. Migrate to the latest 3.5.x first. If the project is older than 3.5, upgrade to the latest 3.5.x, fix deprecation warnings, and get the tests green before touching 4.0. Never jump from 3.2 straight to 4.0.

  3. Baseline: run the full build and tests (./mvnw verify or ./gradlew build) and record failures that exist before migration.

  4. Bump to 4.0.x (parent/BOM or plugin version) and fix the build in this order, running the build after each item:

    1. Starters and modules: starters and removed features. Choose either the classic starters or the new modular ones; Boot 4 split the auto-configuration into many modules, and each technology now has its own *-test starter.

    2. Build files and third-party dependencies: build and dependencies and Kotlin/Java build config.

    3. Jackson 3 (new tools.jackson packages): Jackson 3. A temporary Jackson 2 compatibility module exists; plan to remove it.

    4. Core framework (JSpecify nullability, package relocations, logging, DevTools, PropertyMapper): core framework.

    5. Configuration properties (MongoDB, Spring Session, persistence, Kafka retry): configuration properties. Add spring-boot-properties-migrator temporarily to find renamed keys, and remove it afterwards.

    6. Web and messaging changes (trailing slash matching, HttpMessageConverters, Jersey, Kafka, RabbitMQ): web and messaging.

    7. Tests (Mockito/@MockBean replacement, @SpringBootTest changes, @PropertyMapping): testing.

    8. Actuator and observability modules, health probes: actuator and observability.

  5. Verify with the checklist, pitfalls and resources: full build, tests, startup, actuator health, a smoke test of the main endpoints, and native image build if used.

Build tool notes

  • Maven: change the parent (or spring-boot-dependencies BOM) version, then swap starters in <dependencies>. Use ./mvnw dependency:tree to find stale transitive Jackson 2, Undertow, or Spring Retry usage. The reference files show Gradle snippets; translate the coordinates directly to Maven <dependency> entries.

  • Gradle Kotlin DSL: update the plugin version in plugins {} or the version catalog; use ./gradlew dependencies --configuration runtimeClasspath to inspect resolution.

  • Keep the Spring Boot version in a single place (parent, BOM property, or version catalog entry).

Reference files

FileTopic
01-prerequisites.mdMinimum versions, pre-migration steps
02-starters-and-removed-features.mdModular starters, renamed starters, removed servers/features
03-jackson-3.mdJackson 3 packages, renames, compatibility module
04-core-framework.mdJSpecify, package moves, logging, DevTools, PropertyMapper
05-build-and-dependencies.mdGradle plugin, Spring Retry, Authorization Server, Elasticsearch, Hibernate
06-configuration-properties.mdRenamed and restructured properties
07-web-and-messaging.mdWeb framework, Kafka, RabbitMQ changes
08-testing.mdTest framework changes
09-actuator-and-observability.mdActuator, Micrometer and OpenTelemetry modules
10-kotlin-and-java-build-config.mdKotlin compiler and Java preview configuration
11-checklist-pitfalls-resources.mdFinal checklist, pitfalls, links

Automation

Use OpenRewrite (org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0, https://docs.openrewrite.org/recipes/java/spring/boot4/upgradespringboot_4_0-community-edition) when available, review the diff, and always fetch the version-specific official guide before editing.

Upstream sources (read before migrating)

Fetch the page for the target version; prefer it over this skill when they conflict.

For Boot 3.x patch bumps or Boot 4.0 to 4.1 upgrades, go directly to the target Boot version's release notes and upgrade guide using the official links above. These are dependency upgrades, not JDK migrations; do not route them to java-upgrade.

Related skills, each only if installed (otherwise use the fallback in parentheses):

  • spring-security (Security 7 changes): fall back to the Spring Security 7 migration guide above.

  • spring-observability: fall back to actuator and observability and the Micrometer guide above.

  • java-hibernate-jpa: fall back to the Hibernate ORM 7 migration guide above.

  • java-upgrade (only when a JDK upgrade is explicitly requested): fall back to the target JDK's official migration guide.

  • java-diagnostics (runtime or startup failures): read the full stack trace and mvn dependency:tree / gradle dependencies output yourself.

  • java-testcontainers (Testcontainers 2.0 tests): see testing and the Testcontainers 2 migration notes.

  • kotlin-springboot (Kotlin specifics): see Kotlin and Java build config.

Files

references/02-starters-and-removed-features.md

Module Restructuring and Starter Changes

Critical: Modular Architecture

Spring Boot 4.0 introduces smaller, focused modules replacing large monolithic jars. This requires dependency updates in most projects.

Important for Library Authors: Due to the modularization effort and package reorganization, supporting both Spring Boot 3 and Spring Boot 4 within the same artifact is strongly discouraged. Library authors should publish separate artifacts for each major version to avoid runtime conflicts and ensure clean dependency management.

Migration Strategy: Choose One Approach
Option 1: Technology-Specific Starters (Recommended for Production)

Most technologies covered by Spring Boot now have dedicated test starter companions. This provides fine-grained control.

Complete Starter Reference: For comprehensive tables of all available starters (Core, Web, Database, Spring Data, Messaging, Security, Templating, Production-Ready, etc.) and their test companions, refer to the official Spring Boot 4.0 Migration Guide.

libs.versions.toml:

[versions]
springBoot = "4.0.x" # Target 4.0 patch release

[libraries]
# Core starters with dedicated test modules
spring-boot-starter-webmvc = { module = "org.springframework.boot:spring-boot-starter-webmvc", version.ref = "springBoot" }
spring-boot-starter-webmvc-test = { module = "org.springframework.boot:spring-boot-starter-webmvc-test", version.ref = "springBoot" }

spring-boot-starter-data-jpa = { module = "org.springframework.boot:spring-boot-starter-data-jpa", version.ref = "springBoot" }
spring-boot-starter-data-jpa-test = { module = "org.springframework.boot:spring-boot-starter-data-jpa-test", version.ref = "springBoot" }

spring-boot-starter-security = { module = "org.springframework.boot:spring-boot-starter-security", version.ref = "springBoot" }
spring-boot-starter-security-test = { module = "org.springframework.boot:spring-boot-starter-security-test", version.ref = "springBoot" }

build.gradle.kts:

dependencies {
    implementation(libs.spring.boot.starter.webmvc)
    implementation(libs.spring.boot.starter.data.jpa)
    implementation(libs.spring.boot.starter.security)

    testImplementation(libs.spring.boot.starter.webmvc.test)
    testImplementation(libs.spring.boot.starter.data.jpa.test)
    testImplementation(libs.spring.boot.starter.security.test)
}
Option 2: Classic Starters (Quick Migration, Temporary)

The classic starters restore the Boot 3 module granularity, not the Boot 3 starters. Verified on Boot 4.x with a migrated JPA + security + web project:

  • spring-boot-starter-classic = spring-boot-starter + spring-boot-autoconfigure-classic: all auto-configuration modules, but without their library dependencies.

  • spring-boot-starter-test-classic = spring-boot-starter-test + all the *-test modules (webmvc, data-jpa, security, ...).

  • You still declare the technology starters (spring-boot-starter-webmvc, -data-jpa, -security, ...): with only the classic starters the build fails on missing jakarta.persistence, Spring Security and Jackson classes.

  • They do not bring back the old packages or @MockBean: the test/auto-configuration imports must still be migrated (see the testing reference).

  • spring-boot-starter-web itself still resolves in Boot 4.x as a deprecated alias of spring-boot-starter-webmvc.

libs.versions.toml:

[libraries]
spring-boot-starter-classic = { module = "org.springframework.boot:spring-boot-starter-classic", version.ref = "springBoot" }
spring-boot-starter-test-classic = { module = "org.springframework.boot:spring-boot-starter-test-classic", version.ref = "springBoot" }

build.gradle.kts:

dependencies {
    implementation(libs.spring.boot.starter.classic)
    implementation(libs.spring.boot.starter.webmvc) // technology starters are still required
    testImplementation(libs.spring.boot.starter.test.classic)
}

Note: the Spring Boot migration guide recommends eventually migrating away from the classic starters (whether and when they are removed is not stated there). Plan migration to technology-specific starters.

Option 3: Direct Module Dependencies (Advanced)

For explicit control over transitive dependencies:

libs.versions.toml:

[libraries]
spring-boot-webmvc = { module = "org.springframework.boot:spring-boot-webmvc", version.ref = "springBoot" }
spring-boot-webmvc-test = { module = "org.springframework.boot:spring-boot-webmvc-test", version.ref = "springBoot" }
Renamed Starters (Breaking Changes)

Update these starter names in your libs.versions.toml:

Spring Boot 3.xSpring Boot 4.0Notes
spring-boot-starter-webspring-boot-starter-webmvcExplicit naming
spring-boot-starter-web-servicesspring-boot-starter-webservicesHyphen removed
spring-boot-starter-aopspring-boot-starter-aspectjOnly needed if using org.aspectj.lang.annotation
spring-boot-starter-oauth2-authorization-serverspring-boot-starter-security-oauth2-authorization-serverSecurity namespace
spring-boot-starter-oauth2-clientspring-boot-starter-security-oauth2-clientSecurity namespace
spring-boot-starter-oauth2-resource-serverspring-boot-starter-security-oauth2-resource-serverSecurity namespace

Migration Example (libs.versions.toml):

[libraries]
# Old (Spring Boot 3.x)
# spring-boot-starter-web = { module = "org.springframework.boot:spring-boot-starter-web", version.ref = "springBoot" }
# spring-boot-starter-oauth2-client = { module = "org.springframework.boot:spring-boot-starter-oauth2-client", version.ref = "springBoot" }

# New (Spring Boot 4.0)
spring-boot-starter-webmvc = { module = "org.springframework.boot:spring-boot-starter-webmvc", version.ref = "springBoot" }
spring-boot-starter-security-oauth2-client = { module = "org.springframework.boot:spring-boot-starter-security-oauth2-client", version.ref = "springBoot" }
AspectJ Starter Clarification

Only include spring-boot-starter-aspectj if you're actually using AspectJ annotations:

// Only needed if code uses org.aspectj.lang.annotation package
import org.aspectj.lang.annotation.Aspect
import org.aspectj.lang.annotation.Before

@Aspect
class MyAspect {
    @Before("execution(* com.example..*(..))")
    fun beforeAdvice() { }
}

If not using AspectJ, remove the dependency.

Removed Features and Alternatives

Embedded Servers
Undertow Removed

Undertow is completely removed - not compatible with Servlet 6.1 baseline.

Migration:

  • Use Tomcat (default) or Jetty

  • Do not deploy Spring Boot 4.0 apps to non-Servlet 6.1 containers

libs.versions.toml:

[libraries]
# Remove Undertow
# spring-boot-starter-undertow = { module = "org.springframework.boot:spring-boot-starter-undertow", version.ref = "springBoot" }

# Use Tomcat (default) or Jetty
spring-boot-starter-jetty = { module = "org.springframework.boot:spring-boot-starter-jetty", version.ref = "springBoot" }

build.gradle.kts:

dependencies {
    implementation(libs.spring.boot.starter.webmvc) {
        exclude(group = "org.springframework.boot", module = "spring-boot-starter-tomcat")
    }
    implementation(libs.spring.boot.starter.jetty) // Alternative to Tomcat
}
Session Management
Spring Session Hazelcast and MongoDB Removed

Maintained by respective teams, no longer in Spring Boot dependency management.

Migration (libs.versions.toml):

[versions]
hazelcast-spring-session = "3.x.x" # Check Hazelcast documentation
mongodb-spring-session = "4.x.x"   # Check MongoDB documentation

[libraries]
# Explicit versions required
spring-session-hazelcast = { module = "com.hazelcast:spring-session-hazelcast", version.ref = "hazelcast-spring-session" }
spring-session-mongodb = { module = "org.springframework.session:spring-session-data-mongodb", version.ref = "mongodb-spring-session" }
Reactive Messaging
Pulsar Reactive Removed

Spring Pulsar dropped Reactor support - reactive Pulsar client removed.

Migration:

  • Use imperative Pulsar client

  • Or migrate to alternative reactive messaging (Kafka, RabbitMQ)

Testing
Spock Framework Removed

Spock does not yet support Groovy 5 (required for Spring Boot 4.0).

Migration:

  • Use JUnit 5 with Kotlin

  • Or wait for Spock Groovy 5 compatibility

Build Features
Executable Jar Launch Scripts Removed

Embedded launch scripts for "fully executable" jars removed (Unix-specific, limited use).

build.gradle.kts (remove):

// Remove this configuration
tasks.bootJar {
    launchScript() // No longer supported
}

Alternatives:

  • Use java -jar app.jar directly

  • Use Gradle Application Plugin for native launchers

  • Use systemd service files

Classic Uber-Jar Loader Removed

The classic uber-jar loader has been removed. Remove any loader implementation configuration from your build.

Maven (pom.xml) - remove:

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <loaderImplementation>CLASSIC</loaderImplementation> <!-- REMOVE THIS -->
            </configuration>
        </plugin>
    </plugins>
</build>

Gradle (build.gradle.kts) - remove:

tasks.bootJar {
    loaderImplementation = org.springframework.boot.loader.tools.LoaderImplementation.CLASSIC // REMOVE THIS
}

Requirements and compatibility

Written for: GitHub Copilot

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

First committed by
GitHub avatar of jduboisjdubois
Publisher
GitHub (Official)
Distributed by
GitHub
Source
github/awesome-copilot · skills/spring-boot-4-migration · commit 797337f
Licence
MIT License (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced
Contributors
jdubois

AutoGineer is not affiliated with or endorsed by jdubois or GitHub.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download spring-boot-4-migration.zip