Spring Boot 4 Migration
GitHubOfficialFirst committed by jduboisDistributed by GitHub
- Skill
- Workflow
- Software development
- MIT
- No issues found
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
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/github/spring-boot-4-migration/downloadUnzip 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
latestor 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
Detect the current state
Boot version:
pom.xml(spring-boot-starter-parent/ BOM version),build.gradle(.kts)(org.springframework.bootplugin), orgradle/libs.versions.toml.Build tool:
pom.xml+mvnwmeans Maven;build.gradle.kts/build.gradlemeans 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.
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.
Baseline: run the full build and tests (
./mvnw verifyor./gradlew build) and record failures that exist before migration.Bump to 4.0.x (parent/BOM or plugin version) and fix the build in this order, running the build after each item:
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
*-teststarter.Build files and third-party dependencies: build and dependencies and Kotlin/Java build config.
Jackson 3 (new
tools.jacksonpackages): Jackson 3. A temporary Jackson 2 compatibility module exists; plan to remove it.Core framework (JSpecify nullability, package relocations, logging, DevTools,
PropertyMapper): core framework.Configuration properties (MongoDB, Spring Session, persistence, Kafka retry): configuration properties. Add
spring-boot-properties-migratortemporarily to find renamed keys, and remove it afterwards.Web and messaging changes (trailing slash matching,
HttpMessageConverters, Jersey, Kafka, RabbitMQ): web and messaging.Tests (Mockito/
@MockBeanreplacement,@SpringBootTestchanges,@PropertyMapping): testing.Actuator and observability modules, health probes: actuator and observability.
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-dependenciesBOM) version, then swap starters in<dependencies>. Use./mvnw dependency:treeto 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 runtimeClasspathto inspect resolution.Keep the Spring Boot version in a single place (parent, BOM property, or version catalog entry).
Reference files
| File | Topic |
|---|---|
| 01-prerequisites.md | Minimum versions, pre-migration steps |
| 02-starters-and-removed-features.md | Modular starters, renamed starters, removed servers/features |
| 03-jackson-3.md | Jackson 3 packages, renames, compatibility module |
| 04-core-framework.md | JSpecify, package moves, logging, DevTools, PropertyMapper |
| 05-build-and-dependencies.md | Gradle plugin, Spring Retry, Authorization Server, Elasticsearch, Hibernate |
| 06-configuration-properties.md | Renamed and restructured properties |
| 07-web-and-messaging.md | Web framework, Kafka, RabbitMQ changes |
| 08-testing.md | Test framework changes |
| 09-actuator-and-observability.md | Actuator, Micrometer and OpenTelemetry modules |
| 10-kotlin-and-java-build-config.md | Kotlin compiler and Java preview configuration |
| 11-checklist-pitfalls-resources.md | Final 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.
Boot 4.0 Migration Guide: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
Boot 4.0 Release Notes: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes
Upgrading Spring Boot (incl.
spring-boot-properties-migrator): https://docs.spring.io/spring-boot/upgrading.htmlSystem requirements: https://docs.spring.io/spring-boot/system-requirements.html
Boot releases: https://github.com/spring-projects/spring-boot/releases
Spring Framework 7: https://github.com/spring-projects/spring-framework/wiki/Upgrading-to-Spring-Framework-7.x, https://github.com/spring-projects/spring-framework/wiki/What%27s-New-in-Spring-Framework-7.x
Spring Security 7: https://docs.spring.io/spring-security/reference/migration/index.html
Spring Data 2025.1: https://github.com/spring-projects/spring-data-commons/wiki/Spring-Data-2025.1-Release-Notes
Spring Batch 6: https://docs.spring.io/spring-batch/reference/whatsnew.html
Hibernate ORM 7: https://docs.hibernate.org/orm/7.0/migration-guide/
Jackson 3: https://github.com/FasterXML/jackson/blob/main/jackson3/MIGRATING_TO_JACKSON_3.md
Micrometer: https://github.com/micrometer-metrics/micrometer/wiki/Migration-Guide
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 andmvn dependency:tree/gradle dependenciesoutput 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
- ATTRIBUTION.mdAdded by AutoGineer877 B
- LICENSELicence file added by AutoGineer1.0 KiB
- SKILL.md8.4 KiB
- references/01-prerequisites.md1.9 KiB
- references/02-starters-and-removed-features.md9.6 KiB
- references/03-jackson-3.md4.2 KiB
- references/04-core-framework.md4.2 KiB
- references/05-build-and-dependencies.md6.2 KiB
- references/06-configuration-properties.md3.0 KiB
- references/07-web-and-messaging.md7.3 KiB
- references/08-testing.md6.0 KiB
- references/09-actuator-and-observability.md2.7 KiB
- references/10-kotlin-and-java-build-config.md1.3 KiB
- references/11-checklist-pitfalls-resources.md5.9 KiB
references/07-web-and-messaging.md
Web Framework Changes
Static Resource Locations
PathRequest#toStaticResources() now includes /fonts/** by default.
Security configuration (exclude fonts if needed):
import org.springframework.boot.security.autoconfigure.web.StaticResourceLocation
import org.springframework.boot.security.autoconfigure.web.servlet.PathRequest
@Configuration
@EnableWebSecurity
class SecurityConfig {
@Bean
fun securityFilterChain(http: HttpSecurity): SecurityFilterChain {
http {
authorizeHttpRequests {
// Exclude fonts if needed
authorize(PathRequest.toStaticResources()
.atCommonLocations()
.excluding(StaticResourceLocation.FONTS), permitAll)
authorize(anyRequest, authenticated)
}
}
return http.build()
}
}HttpMessageConverters Deprecation
HttpMessageConverters deprecated due to framework improvements (conflated client/server converters).
Migration:
// Old (Spring Boot 3.x)
import org.springframework.boot.autoconfigure.http.HttpMessageConverters
import org.springframework.context.annotation.Bean
@Configuration
class WebConfig {
@Bean
fun customConverters(): HttpMessageConverters {
return HttpMessageConverters(MyCustomConverter())
}
}
// New (Spring Boot 4.0)
import org.springframework.boot.http.converter.autoconfigure.ClientHttpMessageConvertersCustomizer
import org.springframework.boot.http.converter.autoconfigure.ServerHttpMessageConvertersCustomizer
@Configuration
class WebConfig {
// Separate client and server converters
@Bean
fun clientConvertersCustomizer(): ClientHttpMessageConvertersCustomizer {
return ClientHttpMessageConvertersCustomizer { builder ->
builder.addCustomConverter(MyCustomClientConverter())
}
}
@Bean
fun serverConvertersCustomizer(): ServerHttpMessageConvertersCustomizer {
return ServerHttpMessageConvertersCustomizer { builder ->
builder.addCustomConverter(MyCustomServerConverter())
}
}
}Trailing Slash URL Matching Removed
PathMatchConfigurer#setUseTrailingSlashMatch(true) is removed in Spring Framework 7 / Spring Boot 4.
There is no replacement configuration knob — /foo and /foo/ are no longer treated as the same route.
Migration: register Spring Framework's UrlHandlerFilter as a
FilterRegistrationBean so it runs ahead of the security chain. wrapRequest() makes it forward transparently (no
redirect), preserving the old behavior end-to-end:
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.web.filter.UrlHandlerFilter;
@Configuration
class WebConfig {
// After ForwardedHeaderFilter, before ServletRequestPathFilter and security filters.
private static final int BEFORE_SECURITY_FILTER_ORDER = -101;
@Bean
FilterRegistrationBean<UrlHandlerFilter> trailingSlashHandlerFilter() {
UrlHandlerFilter filter = UrlHandlerFilter.trailingSlashHandler("/**").wrapRequest().build();
FilterRegistrationBean<UrlHandlerFilter> registration = new FilterRegistrationBean<>(filter);
registration.setOrder(BEFORE_SECURITY_FILTER_ORDER);
return registration;
}
}Jersey and Jackson 3 Incompatibility
Jersey 4.0 limitation: Spring Boot 4.0 supports Jersey 4.0, which does not yet support Jackson 3.
Solution: Use spring-boot-jackson2 compatibility module either in place of or alongside spring-boot-jackson:
libs.versions.toml:
[libraries]
spring-boot-starter-jersey = { module = "org.springframework.boot:spring-boot-starter-jersey", version.ref = "springBoot" }
spring-boot-jackson2 = { module = "org.springframework.boot:spring-boot-jackson2", version.ref = "springBoot" }
# Optional: Keep Jackson 3 for non-Jersey parts of application
spring-boot-jackson = { module = "org.springframework.boot:spring-boot-jackson", version.ref = "springBoot" }build.gradle.kts:
dependencies {
implementation(libs.spring.boot.starter.jersey)
implementation(libs.spring.boot.jackson2) // Required for Jersey JSON processing
// Optional: Use Jackson 3 elsewhere in application
// implementation(libs.spring.boot.jackson)
}Note: If using only Jersey in your application, you can replace Jackson 3 entirely with Jackson 2 compatibility module.
Messaging Framework Changes
Kafka Streams Customizer Replacement
Deprecated StreamsBuilderFactoryBeanCustomizer → StreamsBuilderFactoryBeanConfigurer:
// Old (Spring Boot 3.x)
import org.springframework.boot.autoconfigure.kafka.StreamsBuilderFactoryBeanCustomizer
@Configuration
class KafkaStreamsConfig {
@Bean
fun streamsCustomizer(): StreamsBuilderFactoryBeanCustomizer {
return StreamsBuilderFactoryBeanCustomizer { factoryBean ->
factoryBean.setKafkaStreamsCustomizer { streams ->
// Custom config
}
}
}
}
// New (Spring Boot 4.0)
import org.springframework.kafka.config.StreamsBuilderFactoryBeanConfigurer
@Configuration
class KafkaStreamsConfig {
@Bean
fun streamsConfigurer(): StreamsBuilderFactoryBeanConfigurer {
return StreamsBuilderFactoryBeanConfigurer { factoryBean ->
factoryBean.setKafkaStreamsCustomizer { streams ->
// Custom config
}
}
}
}Note: New configurer implements Ordered with default value 0.
Kafka Retry Property Change
application.yml migration:
# Old (Spring Boot 3.x)
spring:
kafka:
retry:
topic:
backoff:
random: true
# New (Spring Boot 4.0)
spring:
kafka:
retry:
topic:
backoff:
jitter: 0.5 # More flexible than booleanRabbitMQ Retry Customizer Split
Spring AMQP moved from Spring Retry → Spring Framework core retry, with customizer split:
// Old (Spring Boot 3.x)
import org.springframework.boot.autoconfigure.amqp.RabbitRetryTemplateCustomizer
@Configuration
class RabbitConfig {
@Bean
fun retryCustomizer(): RabbitRetryTemplateCustomizer {
return RabbitRetryTemplateCustomizer { template ->
// Applies to both RabbitTemplate and listeners
}
}
}
// New (Spring Boot 4.0)
import org.springframework.boot.amqp.autoconfigure.RabbitTemplateRetrySettingsCustomizer
import org.springframework.boot.amqp.autoconfigure.RabbitListenerRetrySettingsCustomizer
@Configuration
class RabbitConfig {
// For RabbitTemplate operations
@Bean
fun templateRetryCustomizer(): RabbitTemplateRetrySettingsCustomizer {
return RabbitTemplateRetrySettingsCustomizer { settings ->
settings.retryPolicySettings.maxRetries = 5L
}
}
// For message listeners
@Bean
fun listenerRetryCustomizer(): RabbitListenerRetrySettingsCustomizer {
return RabbitListenerRetrySettingsCustomizer { settings ->
settings.retryPolicySettings.maxRetries = 3L
}
}
}These customizers exist since Spring Boot 4.0.0 (maxRetries counts retries after the first attempt, unlike the old maxAttempts). In Spring Boot 4.2+ they moved to the org.springframework.boot.rabbitmq.autoconfigure package; adjust the imports when upgrading to 4.2.
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
jdubois
- 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