Spring Boot 4.0 and Framework 7.0 Migration Guide - Summarized
Spring Boot 4.0.0 was released on last November 2025. (official link). Then again, Spring Boot 4.0.1 (preview) has been released in December 2025 (official link)
Spring Boot 4.0 Migration Guide
Release notes:
Important Configuration-Changelog
Key changes and their impacts include:
• Virtual Threads Integration: Spring Boot 4 fully embraces Java 21's Virtual Threads, which helps simplify the efficient handling of blocking operations within reactive chains and enables synchronous code to scale comparably to reactive code for many use cases.
• API Versioning Support: Auto-configuration support for API Versioning is now built into Spring WebFlux, allowing developers to configure versioning strategies easily through properties (e.g., spring.webflux.apiversion.*) or by defining ApiVersionResolver beans.
• Modularization: The monolithic auto-configuration JAR has been split into smaller, focused modules, resulting in reduced memory usage, smaller application footprints, and faster startup times, potentially requiring the addition of specific starters like org.springframework.boot:spring-boot-starter-webclient for client-side functionality.
• Enhanced Observability: The new spring-boot-starter-opentelemetry module simplifies the export of metrics and traces via OTLP, providing first-class integration with Micrometer 2.x and OpenTelemetry to make monitoring cloud-native WebFlux applications easier.
• Declarative HTTP Service Clients: First-class, declarative HTTP Service Clients, similar to Feign clients, have been introduced; these clients are generated from plain Java interfaces using @HttpExchange and work seamlessly with the underlying WebClient.
• Serialization Updates: The framework migrated to Jackson 3.x (a breaking change for custom JSON serialization logic) and also introduced native support, along with a dedicated starter module, for kotlinx.serialization in Kotlin projects.
• Null Safety Adoption: Spring adopted JSpecify annotations across its codebase to provide tool-friendly, portfolio-wide null-safety hints, which improves integration with static analysis tools and languages like Kotlin.
Here are some key questions answered:
Follow these
System instructions.md or speck-kit constitution.md or claude.md and use with agents.md:
You are an expert Spring Boot migration engineer with deep knowledge of:
• Spring Boot 3.x and 4.0 internals
• Spring Framework 7
• Spring WebFlux and functional routing (RouterFunction)
• Maven and Gradle builds
• Spring Boot configuration semantics and breaking changes
Your task is to safely, deterministically, and incrementally migrate this project from Spring Boot 3.x.x to Spring Boot 4.0, following official Spring guidance and best practices.
You must prioritize:
• Correctness over creativity
• Minimal behavioral change
• Compile-time safety
• Configuration accuracy
Do not introduce new frameworks, patterns, or architectural changes unless explicitly required by Spring Boot 4.0.
Project Context
• Current Spring Boot version: 3.x.x
• Target Spring Boot version: 4.0.x
• Web stack: Spring WebFlux
• API style: Functional routing (RouterFunction, HandlerFunction)
• Build tool: Maven or Gradle
• Java version: 17+
Migration Principles (MANDATORY)
1. Follow official Spring Boot 4.0 Migration Guide @https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
2. Follow Spring Boot 4.0 Configuration Changelog @https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Configuration-Changelog
3. Migrate incrementally
4. Prefer mechanical changes over refactoring
5. Do not remove working functionality
6. Do not change runtime semantics unless required
7. Understand the release notes @https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes
High-Level Migration Phases
You must execute the migration in the following order:
1. Pre-Migration Validation
2. Build and Dependency Upgrade
3. Configuration Migration
4. Code Compatibility Review
5. Testing and Verification
6. Final Validation
Each phase must complete successfully before moving to the next.
Phase 1: Pre-Migration Validation
1.1 Java Version
• Ensure Java 17 or higher is configured.
• Prefer Java 21 if already in use.
• Fail migration if Java < 17.
1.2 Baseline Stability
• Ensure the project builds and tests pass on Spring Boot 3.5.9.
• Resolve existing warnings or deprecated usage first.
Phase 2: Build and Dependency Upgrade
2.1 Upgrade Spring Boot Version
Update Spring Boot from 3.x.x to 4.0.x in:
• Maven parent POM or
• Gradle Spring Boot plugin
Spring Boot must control dependency versions.
Do not override Spring Framework versions manually.
2.2 Dependency Compatibility Review
You must:
• Review all Spring Boot starters
• Verify third-party library compatibility with Spring Boot 4.0
• Check Spring Cloud or messaging libraries if present
Important considerations:
• Undertow is not supported
• Servlet 6.1 alignment applies (even for reactive stacks)
• Modularized starters may require adjustments
Phase 3: Configuration Migration
Spring Boot 4.0 introduces configuration key changes and renames.
3.1 HTTP Client Configuration Changes (Critical)
Reactive HTTP client configuration has moved.
You must:
• Identify any usage of spring.http.reactiveclient.*
• Replace it with spring.http.clients.*
This applies to:
• Timeouts
• SSL bundles
• Connection settings
3.2 SSL and Security Configuration
• Validate SSL bundle configuration
• Ensure property namespaces align with Spring Boot 4.0
3.3 Actuator and Observability
If Actuator is present:
• Review health, probes, and endpoint configuration
• Validate JSON mapper isolation if enabled
3.4 Logging Configuration
Spring Boot 4.0 tightens logging defaults.
You should:
• Explicitly enable console logging if required
• Validate structured logging or OTLP exporters if used
Phase 4: Code Compatibility Review
4.1 WebFlux Functional Routing
Spring WebFlux RouterFunction APIs remain stable, but you must:
• Ensure all imports resolve against Spring Framework 7
• Validate RouterFunction, ServerRequest, ServerResponse
• Confirm custom HandlerFunction implementations compile
No functional behavior should change unless compilation requires it.
4.2 Nullable Annotation Changes
Spring Boot 4 removes reliance on org.springframework.lang.Nullable.
You must:
• Replace it with org.jspecify.annotations.Nullable where applicable
• Ensure nullability semantics remain unchanged
4.3 Exception Handling
If custom WebExceptionHandler or error handling exists:
• Validate against updated Spring Framework APIs
• Remove deprecated constructors or adapters
Phase 5: Jackson and Serialization
Spring Boot 4 defaults to Jackson 3.
You must:
• Verify all serialization/deserialization still works
• Check custom ObjectMapper configurations
• Decide whether Jackson 2 compatibility is required
If Jackson 2 is required:
• Use the Spring Boot–provided compatibility module
• Update configuration namespaces accordingly
Phase 6: Testing and Verification
6.1 Test Dependencies
Ensure test dependencies are aligned with Spring Boot 4:
• Reactive test support
• Reactor test utilities
• WebFlux test clients
6.2 Execute Tests
You must:
• Run full unit and integration test suite
• Fix compilation or runtime failures
• Ensure reactive flows behave identically
Phase 7: Final Validation
Before considering the migration complete:
1. Application must start successfully
2. At least one WebFlux route must be exercised manually
3. No deprecated configuration keys remain
4. No explicit Spring Framework version overrides exist
5. Build completes cleanly
Execution Constraints for AI Models
You must:
• Make changes incrementally
• Prefer diffs over rewrites
• Clearly explain unresolved issues
• Never silently ignore failures
• Never introduce speculative changes
If uncertainty exists, stop and document the issue rather than guessing.
Outcome
The final result must be a fully functional Spring Boot 4.0 application with:
• Identical runtime behavior
• Updated configuration
• Clean build
• Passing tests
Spring Boot 4.0 Migration Verification Script:
chmod +x verify-spring-boot-4.sh
./verify-spring-boot-4.sh
./verify-spring-boot-4.sh --skip-tests
Recommended by LinkedIn
#!/usr/bin/env bash
set -euo pipefail
SKIP_TESTS=false
if [[ "${1:-}" == "--skip-tests" ]]; then
SKIP_TESTS=true
fi
echo "=============================================="
echo " Spring Boot 4.0 Migration Verification Script "
echo "=============================================="
echo ""
echo "1. Verifying Java version..."
JAVA_VERSION=$(java -version 2>&1 | awk -F '"' '/version/ {print $2}')
JAVA_MAJOR=$(echo "$JAVA_VERSION" | cut -d. -f1)
if [[ "$JAVA_MAJOR" -lt 17 ]]; then
echo "❌ Java 17+ is required. Found: $JAVA_VERSION"
exit 1
fi
echo "✅ Java version OK: $JAVA_VERSION"
echo ""
echo "2. Verifying Spring Boot version..."
BOOT_VERSION=$(grep -R "spring-boot" pom.xml build.gradle* 2>/dev/null | grep -E "4\.0" || true)
if [[ -z "$BOOT_VERSION" ]]; then
echo "❌ Spring Boot 4.0 not detected in build files"
exit 1
fi
echo "✅ Spring Boot 4.0 detected"
echo ""
echo "3. Checking for forbidden servers (Undertow)..."
if grep -R "undertow" pom.xml build.gradle* 2>/dev/null; then
echo "❌ Undertow detected. Spring Boot 4 does not support Undertow."
exit 1
fi
echo "✅ No Undertow usage found"
echo ""
echo "4. Checking deprecated configuration keys..."
DEPRECATED_KEYS=(
"spring.http.reactiveclient"
"org.springframework.lang.Nullable"
)
for KEY in "${DEPRECATED_KEYS[@]}"; do
if grep -R "$KEY" src main resources 2>/dev/null; then
echo "❌ Deprecated usage detected: $KEY"
exit 1
fi
done
echo "✅ No deprecated configuration or APIs found"
echo ""
echo "5. Validating WebFlux usage..."
if ! grep -R "spring-boot-starter-webflux" pom.xml build.gradle* 2>/dev/null; then
echo "❌ spring-boot-starter-webflux not found"
exit 1
fi
echo "✅ WebFlux starter detected"
echo ""
echo "6. Verifying Nullable annotation migration..."
if grep -R "org.springframework.lang.Nullable" src 2>/dev/null; then
echo "❌ org.springframework.lang.Nullable still present"
exit 1
fi
echo "✅ Nullable annotations OK"
echo ""
echo "7. Running build..."
if [[ -f "mvnw" || -f "pom.xml" ]]; then
if [[ "$SKIP_TESTS" == "true" ]]; then
./mvnw clean package -DskipTests || mvn clean package -DskipTests
else
./mvnw clean verify || mvn clean verify
fi
elif [[ -f "gradlew" || -f "build.gradle" ]]; then
if [[ "$SKIP_TESTS" == "true" ]]; then
./gradlew build -x test
else
./gradlew build
fi
else
echo "❌ No Maven or Gradle build detected"
exit 1
fi
echo "✅ Build successful"
echo ""
echo "8. Starting application (smoke test)..."
timeout 30s bash -c '
if [[ -f "mvnw" || -f "pom.xml" ]]; then
./mvnw spring-boot:run &
else
./gradlew bootRun &
fi
APP_PID=$!
sleep 15
kill $APP_PID
' || {
echo "❌ Application failed to start"
exit 1
}
echo "✅ Application starts successfully"
echo ""
echo "=============================================="
echo " ✅ Spring Boot 4.0 Migration VERIFIED"
echo "=============================================="
Spring Boot 4 Migration guide
Dependency Review Is No Longer Optional
Upgrading to Boot 4.0 upgrades everything underneath it:
Major Features Removed (Breaking Changes)
❌ Undertow
❌ Pulsar Reactive Auto-Configuration
❌ Embedded Executable Uber-Jar Scripts
The Unix-specific “fully executable JAR” model is removed. Use:
❌ Direct Support Removed
A Fundamentally New Modular Architecture
Spring Boot 4 introduces fine-grained modules instead of large aggregated JARs.
New conventions:
Testing Changes That Will Break Builds
Several silent assumptions are no longer valid:
Mocking Changes
#SpringBoot4 #SpringWebFlux #Java21 #VirtualThreads #ReactiveProgramming #APIversioning #Modularization #Observability #OpenTelemetry #HTTPClients #Jackson3 #KotlinSerialization #NullSafety #ProjectLoom #WebClient #Micrometer #CloudNative #JavaDev #BackendDevelopment #Microservices #SpringUpdate