How to use spring-boot-properties-migrator for Spring Boot 4

Mar 5, 2026

I was in the middle of upgrading my application to Spring Boot 4 when I realized I had no idea which properties in my configuration files were actually deprecated. My application.properties had grown over several years - dozens of datasource settings, actuator configs, Jackson customizations, and God knows what else. I couldn’t manually check every single one against Spring’s documentation.

That’s when I found spring-boot-properties-migrator. This tool is a lifesaver for anyone upgrading to Spring Boot 4.

The Problem

Spring Boot 4 marks numerous properties as deprecated. These aren’t just cosmetic warnings - many of these properties will be removed in Spring Boot 4.2.0. If you’re like me, you probably have configuration files that look something like this:

My application.properties (excerpt):
─────────────────────────────────────
spring.datasource.hikari.connection-timeout=30000
spring.jackson.date-format=yyyy-MM-dd
server.tomcat.max-threads=200
spring-boot.admin.client.url=http://localhost:8080

Which of these are deprecated? I had no idea. And frankly, I didn’t want to spend hours comparing my config against release notes.

What is Properties Migrator?

The properties migrator is a runtime tool that automatically detects when your application uses deprecated properties. It logs warnings at startup (and during runtime when properties are accessed) telling you:

Which property is deprecated
What replaced it
Since which version

Think of it as having a knowledgeable colleague review your configuration files and point out everything that’s about to break.

Adding the Dependency

The migrator is a runtime dependency - you add it, run your app, fix the warnings, then remove it before deploying to production.

For Maven, add this to your pom.xml:

<dependencies>
    <!-- Your existing dependencies -->

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-properties-migrator</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies>

For Gradle, add this to your build.gradle:

dependencies {
    // Your existing dependencies

    runtimeOnly("org.springframework.boot:spring-boot-properties-migrator")
}

What You’ll See

Once added, start your application. You’ll see warnings like this in your logs:

Property 'spring.datasource.hikari.connection-timeout' is deprecated:
  Use 'spring.datasource.hikari.pool-name' instead.
  Deprecated since: 3.2.0, for removal in: 4.2.0
─────────────────────────────────────────────────────────

Property 'spring.jackson.date-format' is deprecated:
  Use Jackson's built-in date handling or configure via ObjectMapper.
  Deprecated since: 3.0.0, for removal in: 4.2.0

The migrator doesn’t just check application.properties - it also catches:

application.yml
@Value annotations in your code
Property binding via @ConfigurationProperties
Any programmatic property access

My Experience

Here’s what happened when I added the migrator to my project:

Before (after adding migrator):
─────────────────────────────────
 WARN - Property 'server.tomcat.max-threads' is deprecated
      - Use 'server.tomcat.threads.max' instead
 WARN - Property 'spring.boot.admin.client.url' is deprecated
      - No replacement - this feature was removed
 WARN - Property 'spring.datasource.hikari.connection-timeout' is deprecated
      - Use 'spring.datasource.hikari.connect-timeout' instead

Three hours later, I had fixed all the deprecated properties in my configuration. The migrator gave me exactly what I needed - specific, actionable guidance for each deprecated setting.

The Migration Workflow

Here’s how I recommend using this tool:

Phase 1: Discovery (Add migrator)
──────────────────────────────────
1. Add spring-boot-properties-migrator dependency
2. Run your application
3. Collect all deprecation warnings

Phase 2: Fix (Update configs)
─────────────────────────────
4. Fix each deprecated property
5. Verify no more warnings

Phase 3: Cleanup (Remove migrator)
──────────────────────────────────
6. Remove the dependency before production

Important Notes

A few things I learned the hard way:

Runtime only - This dependency should only be on runtime scope. It instruments the environment at startup and adds overhead you don’t want in production.
Not just startup - The migrator tracks property access throughout your application lifecycle, not just at startup. You might see warnings appear as different parts of your application initialize.
Check all profiles - If you have application-dev.properties, application-prod.properties, or any profile-specific files, run with each profile active to catch all deprecated properties.
Actuator endpoints - The migrator output is visible in your logs. If you have an actuator endpoint that exposes property information, you might want to review what’s being logged.

Why This Matters

Upgrading to Spring Boot 4 isn’t just about Java 17 compatibility. The Spring team is using this release to clean up years of accumulated deprecated configurations. Properties that have been hanging around since Spring Boot 1.x are finally being removed.

Without the migrator, you’d have to:

Manually review every property in your configuration
Search through Spring Boot release notes across multiple versions
Hope you didn’t miss anything

The properties migrator automates this entire process. It’s not optional - it’s essential.

Conclusion

If you’re upgrading to Spring Boot 4, add the properties migrator immediately. Let it guide your configuration updates, then remove it before you deploy. Your future self will thank you when your application starts cleanly on Spring Boot 4 without any deprecation warnings.

Quick Reference:
────────────────
Maven:   <scope>runtime</scope>
Gradle:  runtimeOnly()
Action:  Add → Run → Fix → Remove

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Spring Boot Properties Migrator

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!