Spring Boot 3 → 4 Migration

Official: 4.0 Migration Guide, 4.1 Release Notes. Checked against Boot 4.1.1 on 2026-10-17.

New Boot 4 features (RestTestClient, HTTP service clients, API versioning, native resilience, JSpecify) are covered in ../../creating-springboot-projects/references/spring-boot-4-features.md. This file covers what must change.

Contents

1. Targets
2. Strategy
3. Phase 1: Dependencies
4. Phase 2: Code
5. Phase 3: Tests
6. Phase 4: Configuration
7. Upgrading from 4.0 to 4.1
8. Verification and common failures
9. Checklist

Targets

Go from 3.x straight to 4.1. Clear 4.0 deprecations on the way: 4.1 removes everything deprecated in 4.0.

Strategy

Spring recommends moving off the classic starters eventually.

Phase 1: Dependencies

@Async, @Transactional, @Cacheable, and native @Retryable/@ConcurrencyLimit use Spring AOP proxies. They do not need the AspectJ starter.

Phase 2: Code

Jackson 3

Group ID and packages change for jackson-core and jackson-databind only. jackson-annotations keeps com.fasterxml.jackson.core and the com.fasterxml.jackson.annotation package on purpose.

@Component
class JacksonConfig implements JsonMapperBuilderCustomizer {
    public void customize(JsonMapper.Builder builder) {
        builder.changeDefaultPropertyInclusion(
            incl -> incl.withValueInclusion(JsonInclude.Include.NON_NULL));
    }
}

Libraries that bring their own Jackson 2 serializers (some Redis, Kafka, or HTTP client setups) need their Jackson 3 variants. For Spring Data Redis 4, see ../../code-reviewer/references/performance-patterns.md#distributed-caching-redis.

Package relocations

Spring Retry → native resilience

1. Remove spring-retry.
2. Replace @EnableRetry with @EnableResilientMethods on a @Configuration class. It is required; Boot does not auto-enable it.
3. Imports: org.springframework.retry.annotation.* → org.springframework.resilience.annotation.*.
4. Parameters: retryFor → includes; backoff = @Backoff(delay = 1000, multiplier = 2) → delay = 1000, multiplier = 2; maxAttempts (total calls) → maxRetries (retries after the first call): maxAttempts = 4 becomes maxRetries = 3.
5. @Recover has no native equivalent. Catch the final exception in the caller, or use RetryTemplate.
6. Circuit breakers stay on Resilience4j (resilience4j-spring-boot4, needs the AspectJ starter).

Optional modernization

Not required for the upgrade. Do it after the build is green:

• Manual HttpServiceProxyFactory beans → @ImportHttpServices; configure groups with spring.http.serviceclient.<group>.base-url and shared settings with spring.http.clients.*.
• Custom API-versioning filters → spring.mvc.apiversion.* and version = "..." on mappings.

Details: ../../creating-springboot-projects/references/spring-boot-4-features.md.

Phase 3: Tests

@AutoConfigureWebTestClient is for the reactive WebTestClient. It does not replace TestRestTemplate.

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@AutoConfigureRestTestClient
class UserControllerTest {
    @Autowired RestTestClient client;

    @Test
    void getsUser() {
        client.get().uri("/users/1").exchange()
              .expectStatus().isOk()
              .expectBody(User.class);
    }
}

Phase 4: Configuration

Jackson property families in 4.1:

Run the app once with spring-boot-properties-migrator on the classpath. It reports renamed properties at startup. Remove it afterwards.

Upgrading from 4.0 to 4.1

• Items deprecated in 4.0 are removed.
• spring.data.jpa.repositories.bootstrap-mode=deferred now fails at startup if no suitable AsyncTaskExecutor bean exists. With lazy, the auto-configured bootstrap executor is no longer set.
• jOOQ 3.20 is the minimum, and it requires Java 21.
• The Maven plugin no longer skips test AOT processing on -DskipTests. Use -Dmaven.test.skip=true.
• The layertools jar mode is removed. Use -Djarmode=tools.
• Tomcat's temporary base directory is deleted on shutdown. Set server.tomcat.basedir if you need it to persist.
• Derby is deprecated. Move to H2 or HSQLDB.

Verification and common failures

After each phase: ./mvnw clean verify (or ./gradlew build), start the app, and check /actuator/health.

Checklist

Phase 1: Dependencies

• Boot 4.1.x; webmvc, restclient/webclient, flyway/liquibase starters
• AspectJ starter kept only for real AspectJ use
• Module test starters (or -test-classic); spring-boot-starter-security-test
• spring-retry removed; Jackson 3 coordinates; Testcontainers 2 coordinates

Phase 2: Code

• Jackson 3 imports, classes, customizers
• Package relocations (EntityScan, BootstrapRegistry, WebMvcTest)
• Native resilience with @EnableResilientMethods

Phase 3: Tests

• @MockitoBean / @MockitoSpyBean; no mocks in @TestConfiguration
• @AutoConfigureMockMvc / @AutoConfigureTestRestTemplate or RestTestClient

Phase 4: Configuration

• Properties migrated (spring-boot-properties-migrator run once)
• Health probes and DevTools defaults reviewed

References

• Spring Boot 4.0 Migration Guide, 4.1 Release Notes
• Spring Framework 7.0 What's New
• Jackson 3 migration
• Core Spring Resilience Features