Enforcing JDK Version and Dependency Convergence with the Maven Enforcer Plugin

Desired outcome

Configure a Maven project so that the build aborts if any of the following occurs:

• The JDK used to run Maven is older than a specified minimum version.
• Two or more different versions of the same dependency appear in the effective classpath.

This prevents subtle runtime class‑path conflicts and guarantees that developers and CI agents use a supported Java release.

Prerequisites

• Maven 3.6.0 or newer installed and available on PATH.
• A Maven project with a pom.xml file that you can edit (write access required).
• Network access to Maven Central to download the Enforcer plugin (version 3.0.0 or later).

Procedure

1. Open the project’s pom.xml in a text editor.
2. Locate the <build> section. If it does not contain a <plugins> element, add one.
3. Add an execution of the Maven Enforcer Plugin bound to the verify lifecycle phase (or any phase that runs after dependency resolution, e.g., install).
4. Inside the plugin configuration, define two rules: <requireJavaVersion> and <dependencyConvergence>.
5. Save the file and commit the change if you use version control.

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-enforcer-plugin</artifactId>
      <version>3.0.0</version>
      <executions>
        <execution>
          <id>enforce-java-and-deps</id>
          <phase>verify</phase>
          <goals>
            <goal>enforce</goal>
          </goals>
          <configuration>
            <rules>
              <requireJavaVersion>
                <version>11</version>
              </requireJavaVersion>
              <dependencyConvergence/>
            </rules>
            <fail>true</fail>
          </configuration>
        </execution>
      </executions>
    </plugin>
  </plugins>
</build>

Expected checks

When you run a build that includes the verify phase (e.g., mvn clean install or mvn verify), the Enforcer plugin will:

• Print an informational line showing the required Java version, e.g., [INFO] Required Java version is 11.
• If the running JDK is older than the specified version, the build fails with a message like [ERROR] Failed while enforcing requireJavaVersion: Required Java version is 11 but you are using 1.8.0_292.
• If any artifact appears with multiple versions, the failure message includes [ERROR] Failed while enforcing dependencyConvergence: Found multiple versions of org.apache.commons:commons-lang3 in the dependency tree.

When both rules are satisfied, the build proceeds normally and you will see the plugin execution reported as successful:

[INFO] --- maven-enforcer-plugin:3.0.0:enforce (enforce-java-and-deps) @ my-project ---
[INFO] All enforcer rules passed.

Recovery options

If the build fails because of a JDK version mismatch:

1. Ensure the desired JDK is installed.
2. Set JAVA_HOME to point to that JDK, or configure a Maven toolchain in ~/.m2/toolchains.xml.
3. Re‑run the build.

If the failure is due to dependency convergence:

1. Inspect the dependency tree: mvn dependency:tree -Dverbose.
2. Locate the artifact reported as conflicting.
3. Align the versions by adding a <dependencyManagement> section (or updating existing declarations) to force a single version.
4. Alternatively, exclude the unwanted transitive version with an <exclusion> in the offending dependency.
5. Re‑run the build.

Limitations

• The Enforcer plugin only evaluates its rules when bound to a lifecycle phase. If you omit the <execution> or bind it to a phase that never runs (e.g., none), the rules are silently ignored, giving a false sense of safety.
• Versions of the plugin prior to 3.0.0 use a different XML schema for rules. Using an older version with the configuration shown above will cause a parse error and halt the build.
• The plugin checks the JDK version used to launch Maven, not the target or source levels set in the maven-compiler-plugin. Ensure both are aligned if you need to enforce a specific language level.

Verification

1. Confirm Maven version: mvn -v. The output should show Apache Maven 3.6.0 or higher.
2. Run a clean build: mvn clean install. Observe that the build succeeds and the Enforcer log lines appear.
3. To test the JDK rule, temporarily set JAVA_HOME to a JDK older than the version specified in the plugin (e.g., JDK 8 when the rule requires 11) and re‑run mvn verify. The build should fail with a requireJavaVersion error.
4. To test dependency convergence, add a direct dependency that forces an older version of a library already present elsewhere (e.g., add <dependency><groupId>org.apache.commons</groupId><artifactId>commons-lang3</artifactId><version>3.5</version></dependency> while another dependency pulls in 3.13). Run mvn verify and expect a dependencyConvergence failure.
5. After each test, revert the change (reset JAVA_HOME or remove the offending dependency) and confirm the build passes again.

Rollback

Adding the Enforcer plugin modifies the pom.xml. To roll back:

1. Remove the entire <plugin> block for maven-enforcer-plugin (or comment it out).
2. Save the file and commit if using version control.
3. Run mvn clean install to verify the build proceeds without the enforcement step.