Always specify and enforce the Maven version to be used
Rationale
Apache Maven is constantly being developed. Although there are no obvious major differences between versions, there are still relevant variations between them.
There are fifteen years between versions 3.0 and 3.9.12. Maven 3.8 required Java 7 at least, whereas from version 3.9 onwards, Java 8 was required.
Some projects can be built with either Maven 3.3 or Maven 3.9.12 without any issues. However, some projects behave differently depending on the Maven version used. This is because the individual Maven versions use different default plugin versions.
These differences can easily be traced in the documentation for the plugin versions at version 3.9.1 and version 3.8.5. For example, Version 3.9.12 uses Maven Compiler Plugin 3.13.0, whereas Version 3.8.5 uses Maven Compiler Plugin 3.1.
Especially in projects with multiple developers or different Maven versions in development and in the CI pipeline, errors can occur that are difficult to trace.
By using the Maven Enforcer plugin to enforce the desired Maven version, you can ensure that the correct Maven version is used and that the build is stable and traceable.
Example
This example demonstrates how to enforce a specific Maven version using the Maven Enforcer plugin.
By specifying a custom error message, the Maven property maven.version, which contains the version of Maven used to execute the build, can also be included in the error message.
Having both the required and effective Maven versions in the error message makes the problem much easier to understand and solve.
Please note that the required Maven version is specified using the Maven property mavenVersion in the configuration shown.
This property is also used by the Maven Wrapper to specify the Maven version to be wrapped.
If mavenVersion is used to configure both the Maven Enforcer plugin and the Maven Wrapper, the two plugins are synchronised.
<properties>
<!-- Property used by the Maven Wrapper plugin and the
Maven Enforcer Plugin so that both can refer to the
same Maven version. -->
<mavenVersion>3.9.10</mavenVersion> (1)
<spm.enforcer-plugin.version>3.6.2</spm.enforcer-plugin.version>
<spm.maven-wrapper-plugin.version>3.3.4</spm.maven-wrapper-plugin.version>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-enforcer-plugin</artifactId>
<version>${spm.enforcer-plugin.version}</version>
<executions>
<execution>
<id>enforce-maven</id>
<goals>
<goal>enforce</goal>
</goals>
<configuration>
<rules>
<requireMavenVersion>
<version>[${mavenVersion}]</version> (2)
<message>
This project requires Maven ${mavenVersion}. You are using Maven
${maven.version}. Please ensure you are using the correct Maven
version via the Maven wrapper. Run mvn wrapper:wrapper to ensure
that the configuration of the Enforcer plugin and the Maven Wrapper
plugin are in sync. (3)
</message>
</requireMavenVersion>
</rules>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-wrapper-plugin</artifactId>
<version>${spm.maven-wrapper-plugin.version}</version>
</plugin>
</plugins>
</build>| 1 | Specifying the required Maven version: |
| 2 | Specifying the Maven version to be enforced by the Maven Enforcer plugin:
It is important to use […] to enforce this exact version.
If the required version were specified as <version>${mavenVersion}</version>, any Maven version from the specified version onwards (>=) would be accepted.
Using <version>[${mavenVersion}]</version> restricts the version to the exact specified Maven version (=).
Details on specifying versions can be found on the Enforcer Version Range Specification page. |
| 3 | The formatting of the message element has been adjusted for this example to make the listing easier to read. |
[INFO] Scanning for projects...
[INFO]
[INFO] --< com.amce.systems.specify.maven.version:specify-maven-version-parent >--
[INFO] Building specify-maven-version-parent 0.1.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- enforcer:3.6.2:enforce (enforce-maven) @ specify-maven-version-parent ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1.734 s
[INFO] Finished at: 2026-03-01T04:38:28Z
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-enforcer-plugin:3.6.2:enforce (enforce-maven) on project specify-maven-version-parent:
[ERROR] Rule 0: org.apache.maven.enforcer.rules.version.RequireMavenVersion failed with message:
[ERROR] This project requires Maven 3.9.10. You are using Maven
[ERROR] 3.9.12. Please ensure you are using the correct Maven
[ERROR] version via the Maven wrapper. Run mvn wrapper:wrapper to ensure
[ERROR] that the configuration of the Enforcer plugin and the Maven Wrapper
[ERROR] plugin are in sync.
[ERROR] -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException
[INFO] Build failures were ignored.