Legacy migration (2.7.x → 3.5.x) — the prelude. Covered in references/spring-boot-2-to-3-migration.md: Java 8/11 → 17 baseline, Jakarta EE namespace migration (javax.* → jakarta.*), Spring Security 5 → 6, Hibernate 5 → 6, observability migration to Micrometer Tracing/Observation, OpenRewrite recipe automation for every step. Reach Boot 3.5 latest patch here, then chain into the next scenario.
Major migration (3.5.x → 4.0) — the bulk of this skill. All 9 phases, the gradual upgrade strategy, and the bridge system below.
Minor version upgrades (4.0 → 4.1, 4.1 → 4.2, etc.) — tracked in references/minor-version-changes.md. Minor versions may deprecate APIs, remove compatibility bridges, change defaults, and introduce new features. Check that file before bumping to any new 4.x minor version.

If your project is on Boot 2.7.x or earlier, start with § "Coming from Spring Boot 2.7?" below, complete the 2 → 3 leg, then return here for the 3 → 4 phases.

Verify APIs Against Current Documentation

Many APIs change across these migrations. When unsure whether an API, property, or pattern is still valid for the target version, look it up rather than relying on model knowledge:

Use Context7 (mcp__claude_ai_Context7__resolve-library-id then mcp__claude_ai_Context7__query-docs) for library docs.
Use WebSearch / WebFetch for breaking-change announcements, CVEs, and community migration reports.
Use gh for release notes (e.g., gh api repos/spring-projects/spring-boot/releases/latest).

Toolchain Version Check (Do This First)

Before starting any migration, detect the project's Java, Kotlin, Maven, and Gradle versions. If any are below the minimums for the target Boot version, upgrade them BEFORE bumping Boot.

Read references/toolchain-versions.md for the minimum/recommended versions table and per-tool upgrade commands.

Coming from Spring Boot 2.7? Start here.

If your project is on Spring Boot 2.7.x (or earlier), do the 2.7 → 3.5 leg FIRST. The two scenarios chain:

Boot 2.7.x  →  Boot 3.5.x latest  →  Boot 4.x
              (this section's prelude)   (the 9 phases below)

Read references/spring-boot-2-to-3-migration.md for the complete 2.7 → 3.5 walkthrough. It covers:

Toolchain bump: Java 8/11 → 17 (re-run the 2.7 build on Java 17 BEFORE bumping Boot, so JDK incompats surface separately from Spring upgrade churn)
Pre-flight on 2.7.18 latest patch: clear all deprecation warnings and add spring-boot-properties-migrator for runtime diagnostics
OpenRewrite automation: one-shot via org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_5 (composes every 3.0 → 3.5 step, including Jakarta migration), or step-by-step per minor for large codebases
Jakarta EE namespace migration (javax.* → jakarta.*)
Spring Security 5 → 6 (WebSecurityConfigurerAdapter removed, lambda DSL required, requestMatchers over antMatchers)
Hibernate 5 → 6 (org.hibernate.orm group ID, ID generator changes, naming strategy, query handling)
Per-minor highlights: 3.0, 3.1, 3.2, 3.3, 3.4, 3.5
Property migration via Properties Migrator + OpenRewrite
Observability migration to Micrometer Tracing / Observation API

When the 2 → 3 leg is verified (build passes on Boot 3.5 latest patch and Properties Migrator prints no warnings), return to the Prerequisites section below and proceed with Phases 1–9 for 3.5 → 4.0.

Prerequisites

For 3.x → 4.0 migration:

Toolchain versions meet minimums (see Toolchain Version Check above)
Source project compiles and tests pass on Spring Boot 3.5.x (latest patch)
Java 17+ is available (Java 21+ recommended, Java 25 supported)
All deprecated API calls from Boot 3.x are resolved where possible
If on Boot 3.4 or earlier, first upgrade to 3.5.x before proceeding

For 4.x → 4.y minor version upgrade:

Project is on the latest patch of the current minor version (e.g., 4.0.x latest)
Review references/minor-version-changes.md for the target version
Check the official release notes for the target version
Resolve any deprecation warnings from the current version

Choose Your Migration Strategy

Strategy 1 — Gradual Upgrade (Recommended for enterprise/large codebases) Read references/gradual-upgrade-strategy.md FIRST. This models migration as a dependency graph: a Day-1 baseline using compatibility bridges, then 6 independent tracks (Starters, Jackson 3, Properties, Security, Testing, Framework 7) completed at your own pace. Key bridges:

spring-boot-starter-classic — restores 3.x monolithic auto-configuration
spring-boot-jackson2 — keeps Jackson 2 code working alongside Boot 4
spring-security-access — bridges legacy AccessDecisionManager/Voter Use this when: multiple teams, many services, phased rollouts, or when complete Jackson 3 / Security 7 migration will take more than one sprint.

Strategy 2 — All-at-Once (below) Execute all 9 phases sequentially in one effort. Best for greenfield projects, small codebases, or single-team ownership.

Automated Migration with OpenRewrite

Before doing manual migration, consider using OpenRewrite recipes to automate the mechanical changes. Run OpenRewrite FIRST to handle bulk find-replace operations, then use this skill's phases to address the remaining manual changes (Security DSL rewrites, behavioral differences, property semantics, etc.).

For the 2.7 → 3.5 leg (run before any 3 → 4 work):

Recipe ID	Coverage
`org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_5`	One-shot 2.x → 3.5: composes 3.0 → 3.1 → 3.2 → 3.3 → 3.4 → 3.5, including Jakarta migration, Spring Security 6, Hibernate 6 coordinates, property renames
`org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0`	Step-by-step: 2.7 → 3.0 only (Jakarta + Boot 3.0 baseline)
`org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_1` … `_3_5`	Per-minor incremental upgrades
`org.openrewrite.java.spring.boot3.SpringBootProperties_3_X`	Property key renames per minor version
`org.openrewrite.java.migrate.jakarta.JakartaEE10`	Standalone Jakarta EE namespace migration (`javax.` → `jakarta.`) when applied outside the Boot upgrade

Catalog: docs.openrewrite.org/recipes/java/spring/boot3. End-to-end 2 → 3 walkthrough: docs.openrewrite.org/running-recipes/popular-recipe-guides/migrate-to-spring-3.

For the 3.5 → 4.0 leg:

Recipe ID	Coverage
`org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0` (Community Edition variant available)	Boot 3.5 → 4.0
`org.openrewrite.java.jackson.UpgradeJackson_2_3`	Jackson 2 → 3 package/import migration
`org.openrewrite.java.spring.boot3.MigrateMockBeanToMockitoBean` (or the equivalent in `rewrite-spring`)	`@MockBean`/`@SpyBean` → `@MockitoBean`/`@MockitoSpyBean`

See: moderne.ai/blog/spring-boot-4x-migration-guide. For the 4.0 recipe specifically: docs.openrewrite.org/recipes/java/spring/boot4/upgradespringboot_4_0-community-edition.

Invocation:

# Maven
./mvnw org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE \
  -Drewrite.activeRecipes=<recipe-id>

# Gradle
./gradlew rewriteRun -Drewrite.activeRecipes=<recipe-id>

Migration Workflow (All-at-Once)

Execute these phases IN ORDER. Each phase must compile and pass tests before proceeding to the next.

Phase 1: Build File Migration

Update Boot/Framework versions, build plugins, and replace deprecated starters with modular equivalents. Add modular test starters for each technology used in tests. Use classic starters as a stopgap if needed.

Read references/build-and-dependencies.md for complete starter mappings, build plugin changes, and step-by-step instructions.

Compile check: Run mvn compile or gradle compileJava — fix any dependency resolution errors before continuing.

Phase 2: Property Migration

Scan all application.properties, application.yml, profile-specific variants, and @SpringBootTest(properties = ...) annotations. Rename changed property keys (Jackson, MongoDB, session, actuator, Hibernate).

Read references/property-changes.md for the complete property mapping.

Phase 3: Jackson 3 Migration

Jackson 3 is the default in Boot 4. Migrate group IDs, packages, and renamed Boot classes (@JsonComponent → @JacksonComponent, etc.). Use spring-boot-jackson2 bridge as a temporary stopgap if needed.

Read references/jackson3-migration.md for complete details.

Phase 4: Package and API Relocations

Fix relocated imports (@EntityScan, BootstrapRegistry, etc.), removed APIs (PropertyMapper.alwaysApplyingNotNull, path matching options), and deprecated converters. Also migrate HTTP client code if applicable.

Read references/api-changes.md for the full list of relocated packages and removed APIs. Also read references/http-clients.md if your project uses RestClient, WebClient, @HttpExchange, or Feign.

Phase 5: Observability Migration

Replace individual Micrometer/OTel dependencies with the consolidated spring-boot-starter-opentelemetry starter, update OTLP properties, and rename observability modules. Actuator is now optional for OTel export.

Read references/observability-migration.md for complete details.

Phase 6: Spring Security 7 Migration

Migrate to Security 7 DSL (lambda-only, no and()), replace removed AuthorizationManager#check, switch to PathPatternRequestMatcher, and update Jackson/SAML integrations. Use spring-security-access bridge if legacy AccessDecisionManager/Voter code cannot migrate immediately.

Read references/spring-security7.md for complete details.

Phase 7: Testing Infrastructure Migration

Replace @MockBean/@SpyBean with @MockitoBean/@MockitoSpyBean (removed, not just deprecated). Add explicit auto-configure annotations for test HTTP clients. Migrate Testcontainers 2 module names/packages and adopt JUnit 6. Add modular test starters for each technology.

Read references/testing-migration.md for complete details.

Phase 8: Spring Framework 7 Specific Changes

Address JSpecify nullability (Kotlin impact), deprecated AntPathMatcher, MVC XML config removal, SpringExtension scope changes, Hibernate 7.1 entity mapping changes, and Spring Retry → Framework core retry migration.

Read references/spring-framework7.md for complete details. Also read references/resilience-migration.md if your project uses Spring Retry, @Retryable, @ConcurrencyLimit, or Resilience4j. Optionally read references/api-versioning.md for new API versioning capabilities introduced in Framework 7.

Phase 9: Final Verification

Run the verification script if available, otherwise manually check:

mvn clean verify or gradle clean build — full compile + tests
Verify application starts: mvn spring-boot:run or gradle bootRun
Check actuator health: curl localhost:8080/actuator/health
Verify liveness/readiness probes (now enabled by default)
Check structured logging output format
Run integration tests against each active Spring profile
Verify Docker image builds if using buildpacks or Jib

Optionally read references/aot-native.md if you plan to adopt AOT processing, GraalVM native images, or the new AOT cache feature.

Minor Version Upgrades (4.0 → 4.1, 4.1 → 4.2, etc.)

When upgrading between Spring Boot 4.x minor versions, follow this process:

1. Check What Changed

Read references/minor-version-changes.md for the target version. Also consult the official release notes:

https://github.com/spring-projects/spring-boot/wiki (Release Notes per version)
https://docs.spring.io/spring-boot/upgrading.html

2. Bridge Removal Awareness

Minor versions are where compatibility bridges get removed. Before upgrading, check whether any bridges you depend on are being dropped:

Bridge	Introduced	Expected Removal
`spring-boot-jackson2`	4.0	4.1 or 4.2
`spring-boot-starter-classic`	4.0	5.0
`spring-boot-starter-test-classic`	4.0	5.0
Deprecated starter names	4.0	5.0

If you are still using a bridge that is being removed in the target version, complete the corresponding migration track BEFORE upgrading.

3. Upgrade Process

Update the Spring Boot version in your build file to the target minor version's latest patch release.
Run mvn compile / gradle compileJava — fix any new compilation errors.
Run the full test suite — fix any test failures.
Review deprecation warnings in both build output and application logs. These signal what will break in the NEXT minor version.
Run verify_migration.sh to confirm migration state.

4. New Features

Each minor version introduces new features and auto-configurations. These are opt-in and don't require action, but you may want to adopt them. Check the "New and Noteworthy" section of each release's notes.

Troubleshooting

Common Compilation Errors

Error	Cause	Fix
`ClassNotFoundException: ...autoconfigure...`	Modular starters needed	Add specific `spring-boot-starter-X`
`NoSuchMethodError: PropertyMapper.alwaysApplyingNotNull`	API removed	Use `always()` instead
`Cannot resolve symbol JsonComponent`	Renamed	Use `@JacksonComponent`
`Package com.fasterxml.jackson does not exist`	Jackson 3 packages	Change to `tools.jackson`
`Cannot resolve symbol MockBean`	Deprecated/removed	Use `@MockitoBean`
`ClassNotFoundException: RestClientBuilderCustomizer`	Elasticsearch change	Use `Rest5ClientBuilderCustomizer`

Quick Fixes

If build won't compile at all after version bump, use spring-boot-starter-classic and spring-boot-starter-test-classic to get running, then incrementally migrate to modular starters. See references/gradual-upgrade-strategy.md for the full Day-1 baseline.
If Jackson 3 migration is blocking, add spring-boot-jackson2 temporarily. This is a first-class bridge — see Track B in the gradual strategy.
If Spring Security changes are extensive, add spring-security-access bridge and upgrade to Security 6.5 preparation steps first (they provide opt-out flags for 7.0 breaking changes). See Track D in the gradual strategy.
For enterprise rollouts across many services, use the Wave 1-4 approach in references/gradual-upgrade-strategy.md to minimize blast radius.

Reference File Index

File	When to read
`references/toolchain-versions.md`	Toolchain check — Java/Kotlin/Maven/Gradle minimums and per-tool upgrade commands
`references/spring-boot-2-to-3-migration.md`	Boot 2.7.x → 3.5.x prelude — Java baseline, Jakarta migration, Hibernate 5 → 6, Security 5 → 6, OpenRewrite recipes, per-minor highlights
`references/gradual-upgrade-strategy.md`	FIRST (for 3 → 4) — migration dependency graph, bridges, independent tracks, enterprise rollout
`references/build-and-dependencies.md`	Phase 1 / Track A — full starter mapping tables, build plugin changes
`references/property-changes.md`	Phase 2 / Track C — all property key renames and value changes
`references/jackson3-migration.md`	Phase 3 / Track B — Jackson 3 packages, APIs, compatibility mode
`references/api-changes.md`	Phase 4 — package relocations, removed APIs, renamed classes
`references/observability-migration.md`	Phase 5 — OpenTelemetry starter, OTLP properties, module renames, Actuator decoupling
`references/spring-security7.md`	Phase 6 / Track D — Security 7 breaking changes and DSL migration
`references/testing-migration.md`	Phase 7 / Track E — MockBean, Testcontainers 2, JUnit 6, RestTestClient
`references/spring-framework7.md`	Phase 8 / Track F — Framework 7 changes, JSpecify, path matching
`references/http-clients.md`	HTTP clients — RestClient, WebClient, @HttpExchange, Feign migration, RestTestClient
`references/api-versioning.md`	API versioning — strategies, semantic ranges, client-side, deprecation, testing
`references/resilience-migration.md`	Resilience — Spring Retry → Framework 7, @Retryable, @ConcurrencyLimit, Resilience4j
`references/aot-native.md`	AOT/Native — BeanRegistrar, RuntimeHints, Spring Data AOT, GraalVM 25, AOT Cache
`references/minor-version-changes.md`	4.x minor upgrades — changes per minor version, bridge removals, new features
`scripts/verify_migration.sh`	Phase 9 — bridge-aware verification with PASS/FAIL/WARN/BRIDGE

Authoritative external sources for each leg are listed at the bottom of the corresponding reference file.

spring-boot-4-migration

Spring Boot 4 Migration Skill

Scope: 2.7.x → 3.5.x → 4.x and 4.x Minor Versions