name: spring-boot-4-migration
description: >
Migrate Spring Boot 3.x → 4.x and stay current across 4.x minor
versions. Covers build/starter changes, Jackson 3, Spring Security 7,
Spring Framework 7, observability (OpenTelemetry/Micrometer), property
and package relocations, testing (JUnit 6, Testcontainers 2, MockitoBean),
HTTP clients, resilience, AOT/native, and API versioning. Supports
all-at-once and gradual upgrade strategies with compatibility bridges.
Java and Kotlin; Maven and Gradle.
Trigger on: "upgrade to Spring Boot 4", "migrate to Boot 4",
"Spring Boot 4 migration", "upgrade spring boot", "gradual upgrade",
"upgrade to 4.1", "Spring Boot 4.1", "update Boot minor version",
or any request involving moving a Spring Boot 3.x project to 4.x
or upgrading between 4.x minor versions.

Spring Boot 4 Migration Skill

Migrate Spring Boot 3.x applications to 4.x and stay current across
minor versions with zero guesswork.

Scope: 3.x → 4.0 and 4.x Minor Versions

This skill covers two scenarios:

1. Major migration (3.x → 4.0): The bulk of this skill — all 9 phases,
   the gradual upgrade strategy, and the bridge system.
2. 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.

Prerequisites

For 3.x → 4.0 migration:

• 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. The Moderne platform and OpenRewrite
project provide recipes for:

• Jackson 2 → 3 package/import migration: org.openrewrite.java.jackson.UpgradeJackson_2_3
• Spring Boot 4.x upgrade: org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_5 (prepare step), then UpgradeSpringBoot_4_0
• @MockBean → @MockitoBean annotation replacement

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.).

See: https://www.moderne.ai/blog/spring-boot-4x-migration-guide

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:

1. mvn clean verify or gradle clean build — full compile + tests
2. Verify application starts: mvn spring-boot:run or gradle bootRun
3. Check actuator health: curl localhost:8080/actuator/health
4. Verify liveness/readiness probes (now enabled by default)
5. Check structured logging output format
6. Run integration tests against each active Spring profile
7. 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:

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

1. Update the Spring Boot version in your build file to the target
   minor version's latest patch release.
2. Run mvn compile / gradle compileJava — fix any new compilation errors.
3. Run the full test suite — fix any test failures.
4. Review deprecation warnings in both build output and application logs.
   These signal what will break in the NEXT minor version.
5. 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

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

Official Sources

Cross-reference with these authoritative resources:

• GA Announcement: https://spring.io/blog/2025/11/20/spring-boot-4-0-0-available-now
• Migration Guide: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
• Release Notes: https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes
• Upgrading Docs: https://docs.spring.io/spring-boot/upgrading.html
• Jackson 3 in Spring: https://spring.io/blog/2025/10/07/introducing-jackson-3-support-in-spring/
• OpenRewrite Recipes: https://www.moderne.ai/blog/spring-boot-4x-migration-guide
• Road to GA blog series: https://spring.io/blog/2025/09/02/road_to_ga_introduction
• Dan Vega walkthrough: https://www.danvega.dev/blog/spring-boot-4-is-here
• Dan Vega sample project: https://github.com/danvega/sb4