Skip to content

Grokem · https://www.grokem.com/programming/application-development/spring-boot-java-21-migration-errors-build-plugin-and-startup-fixes

Application DevelopmentTroubleshooting guide

Spring Boot Java 21 migration errors: build, plugin and startup fixes

Work through the failures that most often appear when a Spring Boot app moves to Java 21, from the build tool to the framework version. Each symptom lists likely causes in order, a fix and a way to confirm it.

Krishna Sharma

Technical Writer

Published
  • 7 min read
  • 0 sec

Tested with
  • Java21
  • Spring Boot3.2
  • Spring Boot4.0
  • Maven
  • Gradle
  • OpenRewrite
Your progress
  1. Spring Boot Java 21 migration errors: build, plugin and startup fixes7 min(finished)
    0%

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.

  1. Upgrade the build tooling.
  2. Run the build on JDK 21 with the Spring Boot version you already have.
  3. 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.

Baseline testson current JDKUpgrade Mavenor Gradleand pluginsBuild on JDK 21with currentSpring BootUpgradeSpring Boot,then rebuildCommitCommitCommit
Upgrade one layer at a time and commit after each stage.

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.

bash
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

  1. 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.
  2. Old build tool. The Maven or Gradle version itself does not support the target JDK.
  3. 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

  1. Print the versions your build really uses. You then know whether cause 3 applies.
  2. 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.
  3. 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.
  4. 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.

bash
mvn -version
mvn clean verify
bash
./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

  1. 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.
  2. 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.
  3. Third-party libraries pinned to old versions. A library you declare yourself does not match the framework generation.

Fix

  1. Read the official migration guide for the target version and list every change that touches your code.
  2. Upgrade in steps if the gap is large, and run the build after each step.
  3. 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.
  4. 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.

bash
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

  1. 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.
  2. Test libraries tied to the old JDK. Mocking or bytecode libraries in your test scope may need newer releases.
  3. 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

  1. Confirm the Surefire version and update it.
  2. Read the first failure in the report, not the last. Later failures are often follow-on effects.
  3. Run one failing test alone to remove ordering effects.
  4. 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.

bash
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

  1. Runtime and build JDK differ. You compiled with JDK 21 but the container image, service unit or IDE run configuration launches the old JDK.
  2. 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.
  3. A dependency incompatible with the new framework generation. The failure appears when the context is built, not at compile time.

Fix

  1. Print the Java version where the app actually runs and make it match the build.
  2. Read the startup log from the first error. The root cause is usually the last "Caused by" entry in the stack trace.
  3. Compare your configuration files with the migration guide for your target version.
  4. 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.

bash
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

ProblemLikely causeFix
Build fails right after switching to JDK 21, with an error from a pluginOld compiler or Surefire plugins in Maven, or a Maven or Gradle version that does not support the target JDKUpgrade 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 versionFramework changes in the target release, a large version gap or libraries pinned to old versionsRead 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 21Outdated Surefire plugin or test libraries tied to the old JDK, or a real behaviour changeUpdate 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 serverThe runtime launches a different JDK from the one used for the buildPrint 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

Finished this article?

How did this strike you?

Be the first to react – it is anonymous.

Community

Questions about this?

Ask in Questions and help and get help from other readers.

Ask a questionBrowse Questions and help

Comments

No comments yet. Share what worked for you, or ask a question.

Keep learning

Picked for this article

Related reading, discussions and learning paths on the same subject.

All in Application Development

Learning paths

Learning pathBeginner

Git, tests and delivery

The everyday safety net of a software project: undo mistakes in Git, get out of the three common Git problems, write tests with pytest and run them on every pull request.

4 lessonsabout 43 minStart

Learning pathIntermediate

Data pipelines you can trust

How data gets from source to report without surprises: the ETL and ELT choice, a first pipeline, cleaning, quality checks, safe re-runs and scheduling.

7 lessonsabout 75 minStart

Choose what we may use. You can change this at any time with “Privacy choices” at the foot of every page. Details are in the Cookie policy and the Privacy policy.

Strictly necessary

Remembers your theme, the lessons you marked as done and this choice. It stays on your device, tracks nothing and cannot be switched off.

Always on
What exactly is collected, and why

Google Analytics

Collects
The pages you view, your device and browser type, your language, how you reached the site and your approximate location (country and city, worked out from your IP address).
Why
To understand which pages and lessons are used, so we can improve them.
Stored
Two cookies, _ga and _ga_<id>, for up to 2 years. Google acts for us; the data is processed by Google, including outside your country.

Grokem’s own counts

Collects
The pages you open and how long you stay, how far you scroll, where you came from, your device type, browser, screen size, language and time zone. Your IP address is turned into a code that changes every day; it is never stored as it is.
Why
To see how long lessons are read and where readers leave. Not shared with anyone.
Stored
A random visitor ID, a visit ID and the time of your last page view in your browser’s storage (gr_vid, gr_sid, gr_last). No name or email is attached.