This guide is organised by symptom. You find the failure you see, check the likely causes from most to least probable, apply the fix and run a check that proves it worked.
It was written for Spring Boot 3.2 and Spring Boot 4.0 applications moving to Java 21. The Spring Boot 4.0 migration guide is titled "Java 21 & Jakarta EE 11", so a move to 4.0 can bring framework changes on top of the JDK change. Exact property names, removed classes and supported Java ranges differ per release. This guide does not list them. Read the official Spring Boot migration guide for your exact target version before you edit code.
Change one layer at a time
Most failed migrations mix three changes in one commit: the JDK, the build plugins and the Spring Boot version. When something breaks, you cannot tell which change caused it.
Split the work into this order. Commit after each stage.
- Upgrade the build tooling.
- Run the build on JDK 21 with the Spring Boot version you already have.
- Upgrade Spring Boot, if your current release does not support Java 21.
This order works because an old Maven or Gradle setup fails before your own code is even compiled. Fixing the tooling first removes the noisiest errors.
Before you start, record a baseline. Run your tests on the current JDK and keep the result. A test that already failed before the migration is not a migration error.
java -version
mvn -version
mvn clean verify
Symptom: the build fails as soon as you switch to JDK 21
You set JDK 21 as the active JDK and the build stops before or during compilation or tests. The error mentions a plugin, an unsupported class file version or a failed build step rather than your own code.
Likely causes, in order of probability
- Old build plugins. Old plugins fail on a newer JDK. For Maven this means the compiler plugin and the Surefire plugin. This is the most common cause.
- Old build tool. The Maven or Gradle version itself does not support the target JDK.
- Wrong JDK in use. Your shell, IDE or CI image still points to the previous JDK, so the error does not come from the change you think.
Fix
- Print the versions your build really uses. You then know whether cause 3 applies.
- Upgrade Maven or Gradle to a release that supports the target JDK. Use the build tool's own documentation to find which release that is.
- In Maven, update the compiler plugin and the Surefire plugin to recent versions. In Gradle, update the Gradle version and any plugins applied in the build.
- Rebuild with the same Spring Boot version as before.
Confirm it worked
The output of the version command shows a Java 21 runtime. A full build finishes without a plugin error. If you use Gradle, the wrapper prints the JVM it runs on.
mvn -version
mvn clean verify
./gradlew --version
./gradlew clean build
Symptom: compile errors after you upgrade Spring Boot
The build tooling is fine, but compilation fails with missing packages, missing classes or changed signatures after you raise the Spring Boot version.
Likely causes, in order of probability
- Framework changes in the target release. Spring Boot 4.0 is described as a major cleanup, modernisation and modularisation, and its guide covers Jakarta EE 11. Imports and dependencies can change.
- Skipped intermediate releases. The app was far behind, so several migrations land at once. Moving one major line at a time gives you smaller error lists.
- Third-party libraries pinned to old versions. A library you declare yourself does not match the framework generation.
Fix
- Read the official migration guide for the target version and list every change that touches your code.
- Upgrade in steps if the gap is large, and run the build after each step.
- Check each dependency you declare explicitly. Remove the explicit version where the framework already manages it, or move to a release built for your target.
- Use OpenRewrite to apply mechanical changes instead of editing every file by hand. If you use STS4, you can start it by right-clicking the application you want to migrate. The exact menu labels depend on your STS4 version, so check what your IDE shows.
The recipe names and configuration for OpenRewrite are not listed here. Take them from the OpenRewrite documentation for your build tool.
Confirm it worked
mvn clean verify or ./gradlew clean build compiles every module. Review the OpenRewrite diff before you commit it, because automated changes still need a human check.
mvn clean verify
Symptom: tests pass on the old JDK and fail on Java 21
The build compiles, but tests fail only after the JDK changes.
Likely causes, in order of probability
- Test runner plugin too old. An outdated Surefire plugin can fail on a newer JDK. Check this first, because it is the same family of cause as the build failure above.
- Test libraries tied to the old JDK. Mocking or bytecode libraries in your test scope may need newer releases.
- A real behaviour change in your code or a dependency. This is the least likely cause and the one you want to find last.
Fix
- Confirm the Surefire version and update it.
- Read the first failure in the report, not the last. Later failures are often follow-on effects.
- Run one failing test alone to remove ordering effects.
- Compare with your baseline from the old JDK. Only failures that are new count as migration errors.
Confirm it worked
The test count and the pass count match your baseline. No test has been skipped or deleted to get a green build.
mvn clean verify
Symptom: the app compiles but fails or behaves differently at startup
The build is green, yet the application does not start, or it starts and a feature misbehaves.
Likely causes, in order of probability
- Runtime and build JDK differ. You compiled with JDK 21 but the container image, service unit or IDE run configuration launches the old JDK.
- Configuration changed between Spring Boot versions. Settings may be renamed or removed in the target release. The migration guide for that version is the place to check.
- A dependency incompatible with the new framework generation. The failure appears when the context is built, not at compile time.
Fix
- Print the Java version where the app actually runs and make it match the build.
- Read the startup log from the first error. The root cause is usually the last "Caused by" entry in the stack trace.
- Compare your configuration files with the migration guide for your target version.
- Update or replace the dependency named in the stack trace.
This guide does not list renamed properties. Do not guess them. Use the official migration guide for your version.
Confirm it worked
The application starts, the log shows the expected Java version, and a request to a known endpoint returns the same response as before the migration.
java -version
Release without regressions
Keep the migration on its own branch. Run the full test suite in CI on JDK 21, not only on a developer machine. Deploy to a staging environment first, and keep the previous build available so you can roll back.
If you target Spring Boot 4.0, plan for more time than a pure JDK change. The framework changes are larger than the compiler changes.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| Build fails right after switching to JDK 21, with an error from a plugin | Old compiler or Surefire plugins in Maven, or a Maven or Gradle version that does not support the target JDK | Upgrade the build tool and the plugins first, then rebuild with the unchanged Spring Boot version and confirm with mvn clean verify or ./gradlew clean build. |
| Compile errors appear after raising the Spring Boot version | Framework changes in the target release, a large version gap or libraries pinned to old versions | Read the official migration guide for the target version, upgrade in steps, drop explicit versions of managed dependencies and use OpenRewrite for mechanical changes. |
| Tests fail only on Java 21 | Outdated Surefire plugin or test libraries tied to the old JDK, or a real behaviour change | Update Surefire, read the first failure, run a failing test alone and compare with the baseline from the old JDK. |
| App starts on a developer machine but not in the container or on the server | The runtime launches a different JDK from the one used for the build | Print java -version where the app runs and align it with the build JDK. |
Frequently asked questions
What should I upgrade first when moving a Spring Boot app to Java 21?
Upgrade the build tooling first: a recent Maven with recent compiler and Surefire plugins, or a Gradle version that supports the target JDK. Old plugins fail on newer JDKs.
Can I automate part of the migration?
Yes. OpenRewrite can apply mechanical changes. In STS4 you can start it by right-clicking the application to migrate. Review the resulting diff before committing.
Does moving to Spring Boot 4.0 involve more than a JDK change?
Yes. The Spring Boot 4.0 migration guide is titled Java 21 & Jakarta EE 11 and describes major cleanup, modernisation and modularisation, so expect framework changes as well.
Where do I find the list of renamed or removed properties?
In the official Spring Boot migration guide for your target version. This guide does not list them, and you should not guess them.
From Grokem: https://www.grokem.com/programming/application-development/spring-boot-java-21-migration-errors-build-plugin-and-startup-fixes









