Migrating to Maven 4

The same project, the same command, the two Maven 3 lines:

The build then succeeds (BUILD SUCCESS), and the jar manifest has the Main-Class of the first declaration: Maven 3.9 merged the two declarations itself. Maven 3.10.0 does not:

This is documented: the Maven 3.10.0 release notes list "Stricter POM validation" among the changes that can break a build coming from 3.9.x ("many WARNINGs from the 3.9 lineage …​ will now FAIL the build"), with duplicated dependency entries and duplicated plugin entries as the examples. The practical consequence for a migration is that Maven 3.10.0 is the better Maven 3 to prepare on: it fails on what Maven 4 will fail on, while 3.9.16 only warns, so a project that is clean on 3.10.0 has already passed the first Maven 4 hurdle.

Source: Maven 3.10.0 Release Notes: Stricter POM validation

The fix is to merge the two declarations into one, which is what Maven 3.9 did silently:

After the merge the project builds on 3.9.16 and on 3.10.0 (BUILD SUCCESS, tests 1 and 1), and the manifest of tidepool-cli carries Main-Class: io.tidepool.cli.Main.

Source: Starting with Maven 4: Duplicate plugin declaration

The guide recommends versions:display-plugin-updates of the Versions Maven Plugin to find the latest Maven 3 version of each plugin, and to avoid, for now, the versions that need Maven 4. Run on tidepool with versions-maven-plugin 2.23.0 on Maven 3.9.16, it separates the two groups by the Maven version each plugin release requires (excerpt, the older Maven 2 lines trimmed):

So on this project the Maven 3 lines of compiler, jar, resources, clean, install, deploy and surefire are the right ones for steps 1 and 2, and the 4.0.0-beta lines are the ones that need Maven 4 (they are pre-releases, not stable). The report has a blind spot, though. It said the specified plugins are "using the latest versions" while maven-antrun-plugin 3.1.0 was pinned and 3.2.0 had been on Central for a year. What flagged the old antrun was Maven’s own plugin validation, which is the other tool of this step:

Maven 3.9.16 printed no such report with the same property, so this check also needs 3.10.0 or Maven 4. The cause is the Plexus injection that Maven 4 no longer promises to support (see the plugins section of the overview). The report suggests upgrading; maven-antrun-plugin 3.2.0 is a Maven 3 release (Central lists it from October 2025), and bumping the single version in the parent removed the report on both 3.10.0 and Maven 4 and left every build green on all three Maven versions. Plugin versions and configuration in general are on Plugins & Their Configuration.

Source: Starting with Maven 4: Upgrade plugins to their latest Maven 3 version, Plugins Validation and versions:display-plugin-updates

Maven 4 needs Java 17 to run, while Maven 3.9 and 3.10 run on Java 8 and later. That is a statement about the JVM that runs Maven, not about the release your code compiles for, which stays 17 here but could stay 8 or 11 with a toolchain (Compiling & Toolchains). Everything on this page ran on JDK 26. Because Maven 3 also runs on JDK 17, the guide suggests moving the build machines (laptops, CI images, containers) to a JDK 17 first. The prepared project builds unchanged on JDK 17 (JetBrains Runtime 17.0.14) with Maven 3.10.0 and with rc-7:

Where Maven is selected is part of this step too: the distributionUrl in .mvn/wrapper/maven-wrapper.properties (Maven Wrapper), a requireMavenVersion enforcer rule (Enforcer), and the CI scripts. The recommended trial is a CI job that builds with Maven 4 beside the one that builds with Maven 3, reports Maven 4 failures as feedback and does not gate releases yet.

Maven 4 rejects the duplicate too, and it reports it twice, once for the subproject and once for the parent that includes it in the reactor:

With the prepared project (merged jar plugin, antrun 3.2.0), rc-7 builds everything: all four reactor entries SUCCESS, tests passing, and the same artifacts. This is the point where the project builds on Maven 3.9.16, Maven 3.10.0 and Maven 4.0.0-rc-7 from the same unchanged build POM, with the model version still 4.0.0, which is the intended state of "test".

Source: Starting with Maven 4: Duplicate plugin declaration

The first line of the output above is the next thing to fix. Maven 4 wants to know where the root of a multi-project build is, and warns when it cannot find out. There are two ways to tell it. A .mvn directory in the root works with Maven 3 too (a committed empty file keeps git from dropping the empty directory), and the root="true" attribute on the root <project> needs model version 4.1.0, so it is for step 3. For the test step use .mvn:

There is a trap here that makes the warning disappear without anyone fixing anything. On a project without a .mvn directory, the first Maven 4 build prints the warning and then creates .mvn/target/project-local-repo itself, so the second build finds a .mvn directory and prints nothing:

The directory is ignored by a target/ rule in .gitignore, so git status shows nothing and the warning never comes back, while the checkout of a colleague or of CI still warns. Commit a real .mvn entry. What the root is used for follows.

Source: Starting with Maven 4: Define project’s root directory

Maven 4’s --fail-on-severity (-fos) option turns log output of a given severity into a build failure and is the guide’s tool for finding what the build is complaining about. It fails before the .mvn fix and passes after it:

With .mvn in place the same command ends in BUILD SUCCESS. Note that any plugin message logged at WARNING counts: the antrun scripts of tidepool print with <echo level="info"> for exactly this reason, because the default level of the Ant echo task is warning, and the first run of this experiment failed on the scripts' own messages. Keep -fos WARN for a CI trial, not as a permanent flag, until your plugins stop logging warnings for normal operation.

The guide says Maven 4 adds ${project.rootDirectory}, ${session.topDirectory} and ${session.rootDirectory} for paths, and that several internal properties, among them executionRootDirectory and multiModuleProjectDirectory, are deprecated or removed. To see what that means in practice, a two-level project (a parent with .mvn and one subproject) defines one POM property per name, and mvn help:effective-pom shows what each became:

"Not resolved" means the text stayed as written, ${...} included. Two lessons. The names the guide calls removed were never available to a POM in this form on the Maven 3 versions tested, so a POM that uses them either never worked or only worked through a plugin’s own expression evaluator; search for them. And the one spelling that works everywhere is the system property ${maven.multiModuleProjectDirectory}, which is why the tidepool deploy URL uses it. The Maven 3.10.0 release notes say session.topDirectory, session.rootDirectory and project.rootDirectory were promoted to regular properties; in this experiment only ${project.rootDirectory} was substituted in POM interpolation on 3.10.0, so test your own expressions before relying on the session.* names in a build that must also run on Maven 3. Replacing a hand-rolled root lookup with ${project.rootDirectory} worked on 3.10.0 and 4 in this experiment (the test project had a .mvn directory).

Source: Starting with Maven 4: Replace removed directory properties and Maven 3.10.0 Release Notes: New Features and Improvements

The guide says the pre-integration-test, post-integration-test, pre-clean, post-clean and similar phases are replaced by before: and after: phases for every phase, and tells you to move bindings. In rc-7 the old names are still accepted: tidepool’s pre-integration-test and post-clean antrun bindings ran without any message. What changed is when a post-clean binding runs. On Maven 3 the clean phase stops before post-clean, so a script bound there ran only when you asked for it by name. On rc-7 it runs as part of every mvn clean:

A script that deletes or regenerates something at post-clean therefore starts firing on every clean build when the project moves to Maven 4. mvnup rewrites the phase names (see below); read the diff, since the new name does what rc-7 already does. The lifecycle tree and the before:/after: phases are on Maven 4: Lifecycle.

Source: Starting with Maven 4: Replace plugin bindings to pre- and post- lifecycle phase

The guide marks as a breaking change that installAtEnd and deployAtEnd default to true in Maven 4: the artifacts of a multi-project build are installed or deployed together after every project has built, so a failure in a later subproject no longer leaves earlier ones half-published. The default belongs to the plugins, not to Maven 4 itself, and the plugin version decides. Pinned to the Maven 3 plugin lines (install 3.2.0), a Maven 4 build behaves like Maven 3. To make the difference visible, the test of tidepool-cli fails on request (-Dfail=true), so the last subproject breaks after model and engine have been built:

Moving only maven-install-plugin and maven-deploy-plugin to 4.0.0-beta-3 (the lines that need rc-6 or later, from the update report above) changes the outcome on rc-7:

With the failing test, the install goal now runs for every subproject but installs nothing (installed jars: 0, and the scratch local repository has no io/tidepool directory). With the tests passing, the Installing lines all appear when the last subproject’s install runs, and mvn deploy does the same:

The -build.pom and the consumer POM in the listing are the two POMs Maven 4 publishes per project, explained on Maven 4: POM Model & Consumer POM. The guide’s advice for a build that depended on the old default (false) is to look for a configuration error that the setting was hiding, rather than to set it back. Install and deploy in general are on Install, Deploy & Distribution Management. Whether it is worth leaving the Maven 3 plugin lines before the migration is finished is a choice: they are pre-releases (beta), and the project can stay on 3.2.0 until Maven 4.0.0 is out.

Source: Starting with Maven 4: Install/deploy at end of build, install:install installAtEnd and deploy:deploy deployAtEnd

To see what the tool does with the problems rather than with a tidy project, it was run on the first state of tidepool, the one with the duplicate plugin and without .mvn:

check leaves the working tree untouched and prints, in the past tense, what apply would do. apply then changed one file and created the .mvn directory. This is the diff, and it is the lesson of this section:

mvnup fixed the duplicate by deleting the first declaration and keeping the last, not by merging them. The build is green, and the jar is wrong: the manifest no longer has a Main-Class.

Merging the two declarations by hand in step 1, as above, gives the manifest with Main-Class: io.tidepool.cli.Main. The rule that follows is this page’s advice, not the tool’s: never run apply without reading git diff, and fix the semantic problems (duplicates with different configuration, version choices) before running it.

Source: Maven Upgrade Tool: Specific upgrades

Starting again from the state at the end of step 2 (jar plugin merged, antrun 3.2.0, .mvn committed), the default mvnup check finds nothing to change:

That is the result of a good step 2: with the default options mvnup only repairs things that Maven 4 would reject. The Maven 4 features need the 4.1.0 model, so they need --model-version 4.1.0, or --all, which adds two strategies to the eleven above (13 in total): "Upgrading POM model version" and "Migrating source configuration to <source> elements".

mvnup -B check --model-version 4.1.0 --all reports four modified POMs. apply then rewrites them (git diff --stat: 4 files changed, 18 insertions, 33 deletions). The parent:

And a subproject (tidepool-engine; tidepool-model and tidepool-cli change the same way):

What happened, item by item, and what to check:

The tool left alone what it does not understand or does not consider wrong: the dependency <version>${project.version}</version> entries (valid, though 4.1.0 can drop them for projects in the same reactor), the pinned plugin versions, the deploy URL, and it did not add root="true", since .mvn was already there.

Source: Maven Upgrade Tool: Basic upgrade workflow and Maven Upgrade Tool: Intelligent Model Inference (Maven 4 only)

Both Maven 3 lines now refuse the project, with the same message, because they do not know the new namespace:

This is the point of no return: from here the only Maven that builds the project is Maven 4. (The consumer POM published for the project is still model 4.0.0, so users of the artifacts are not affected.) On rc-7 the build starts, and then fails in the first subproject:

mvnup replaced the maven.compiler.release property with a <sources> entry, and the Maven 3 compiler plugin pinned in the build (3.16.0) does not read <sources>, so it fell back to its defaults: target 1.8. The mechanics and the other effects of <sources> are on the overview; here only the two ways out matter, and both were run:

With the second option, after all changes, mvn -B -fos WARN clean verify on rc-7 ends in BUILD SUCCESS: four reactor entries, no warnings, no root directory message. Building on JDK 17 gives the same result.

Source: What’s new in Maven 4: New way to declare source directories

mvnup apply --plugins upgrades plugins "known to fail with Maven 4" to their minimum compatible version, not to the latest. On a throw-away POM that pinned a deliberately old line of 27 plugins, the log lists the moves (excerpt):

Plugins that need nothing (here maven-site-plugin, maven-javadoc-plugin, maven-gpg-plugin, maven-release-plugin and others) were left alone. Two points. The target is the oldest version that works (compiler 3.11.0, whereas 3.16.0 is current), so after mvnup you still want to move to the current Maven 3 lines, and a plugin that was already newer than the minimum is not touched. And --plugins also added a <pluginManagement> block with 14 entries to the parent for the plugins that the effective model brought in, which is a large diff to review in an existing build.

Source: Maven Upgrade Tool: Plugin Compatibility & Upgrades

Most of the eleven strategies did nothing for tidepool. A second throw-away project, tidepool-legacy (Java 8 settings, an http: repository, a requireMavenVersion rule capped below 4, a filtered resource, an invalid Automatic-Module-Name and an Ant <script language="javascript">), shows them working. mvnup check reported these changes, and apply made them:

It also added a <pluginManagement> entry for maven-resources-plugin with a nonFilteredFileExtensions list of 33 binary extensions (xlsx, png, jar and so on), which prevents filtering from corrupting binary resources. Two of these deserve a comment:

The strategy for the toolchains plugin did nothing here, because --source 8 is accepted by the JDK used. It acts when the source level is too old for the JDK that runs Maven.

Source: Maven Upgrade Tool: Maven 4 Compatibility Fixes