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

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.html
• System 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 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.