Maven 4 Preview, Build Consumer POM, Compatibility, Migration Planning, and Maven 3 Production Baselines: Diagnostics, Failure Modes, Security, and Performance

1. The migration diagnostic sequence

Use the same disciplined order as earlier chapters, with release status added at the front:

1. Preserve concise error/warning and the exact Maven 3/Maven 4 release identities.
2. Confirm launcher JDK and wrapper/distribution integrity.
3. Inspect declared and effective POMs plus mvnup check output.
4. Inventory active plugins/extensions and lifecycle bindings.
5. Compare dependency/reactor graph and isolated local-repository state.
6. Compare test/report/artifact and consumer-POM evidence.
7. Apply the smallest reversible correction in the candidate lane.
8. Rebuild under both baselines and decide whether rollback remains viable.

2. Failure mode: release candidate is treated as GA

Symptom: a platform document says “Maven 4 is the new production standard” while the official release history still lists 4.0.0-rc-6 under “not yet GA.” The build may be green; the governance statement is still false.

Repair: classify the Maven 4 lane as compatibility/pre-GA evaluation, retain Maven 3.9.16 as the release baseline, and create a release-status gate that must be re-checked on the migration date. Do not solve a status error with a POM edit.

3. Failure mode: Maven 4 is launched on unsupported Java

Maven 4 requires Java 17+. If the CI image still exposes an older runtime, Maven may fail before meaningful project execution. That is different from a Compiler Plugin message saying the application source/target release is unsupported.

# Preserve identity before touching the POM.
java -version
./mvnw -v

# In CI, inspect JAVA_HOME / PATH selection as environment state.
printf 'JAVA_HOME=%s
' "${JAVA_HOME:-unset}"

Least-destructive repair: update the Maven 4 test lane to a Java 17+ runtime while leaving the application's compiler release/toolchain policy unchanged. Re-run Maven 3 on the same launcher JDK where possible so the Maven-core comparison remains controlled.

4. Intentionally broken example: duplicate plugin declaration

Maven 3.9 can warn about some malformed/duplicate plugin declarations that Maven 4 treats more strictly. This is a useful compatibility fixture because the model itself—not the cache—is wrong.

<build>
  <plugins>
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jar-plugin</artifactId>
      <version>3.5.1</version>
    </plugin>
    <!-- Intentionally wrong: same plugin declared twice. -->
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-jar-plugin</artifactId>
      <version>3.5.1</version>
    </plugin>
  </plugins>
</build>

Preserve Maven 3 and Maven 4 outputs. The repair is to merge the intended configuration into one plugin declaration, not to add -X, delete repositories, or downgrade warnings. Then verify both lanes again.

5. Failure mode: plugin or extension uses removed/internal API

A core extension can fail with symptoms such as NoSuchMethodError, ClassNotFoundException, service-loading errors, or bootstrap exceptions before normal lifecycle execution. Treat the exact class/method name as evidence about API coupling.

[ERROR] Failed to load core extension dev.example:legacy-maven-extension:1.2.3
java.lang.NoSuchMethodError: '...internal Maven implementation method...'
    at dev.example.LegacyExtension.initialize(LegacyExtension.java:42)

This is a synthetic log shape, not a claim about a real plugin. The diagnostic action is to identify the exact extension coordinates/source, check its Maven 4 compatibility or upgrade path, and reproduce without production credentials. Removing the extension temporarily can help isolate cause, but only if you understand what functionality/security policy it provided. Do not replace it with an unreviewed third-party fork just to make the test green.

6. Failure mode: consumer POM differs unexpectedly

Symptom: the JAR checksum matches but the installed POM is not byte-identical to the source model 4.1.0 POM. Under Maven 4, that difference can be intentional consumer-POM transformation.

Diagnosis: compare semantic fields: GAV coordinates, packaging, compile/runtime dependency information, exclusions, dependency management where relevant, and repository/publication metadata expected by downstream consumers. Build plugin configuration disappearing from a consumer POM is not itself a defect. A missing runtime dependency would be a defect.

diff -u pom.xml "$ISOLATED_REPO/dev/academy/example/1.0.0/example-1.0.0.pom"   > evidence/build-vs-consumer.diff || true

# Then inspect dependency semantics rather than only textual identity.
grep -E '<modelVersion>|<groupId>|<artifactId>|<version>|<scope>|<dependency>'   evidence/consumer-installed.pom

7. Failure mode: migration has no rollback/output comparison

A migration done directly on the main POM, wrapper, CI image, and release job at once has no clean control group. Even if it works, you cannot attribute differences and rollback becomes a reconstruction exercise.

The repair is procedural: restore the Maven 3 baseline from version control, create an isolated candidate branch/copy, pin both runtimes independently, disable production publishing in the candidate, and regenerate build/test/checksum/effective-model evidence. Rollback is a designed state, not a hopeful git revert after artifacts have already been published.

8. Repository/cache diagnostics without destructive cleanup

If Maven 4 resolves something differently or a stale local artifact hides a missing relationship, repeat the failing command with a new disposable local repository. Do not delete ~/.m2/repository. If the fresh repository succeeds/fails differently, you have isolated repository-state influence and preserved the old state for inspection.

./candidate-m4/mvnw   -Dmaven.repo.local="$PWD/.lab/fresh-m4-repo"   -e clean verify | tee evidence/fresh-repo-e.log

Escalate to -X only if narrower evidence is insufficient, and redact repository/server/environment details before sharing logs. Debug verbosity is not a performance benchmark and can expose configuration context.

9. Performance comparisons come after compatibility correctness

Maven 4 may have performance differences in model building, concurrency, or daemon/shell tooling, but this chapter does not accept speed as a reason to ignore semantic differences. First prove the same intended project scope/tests/artifacts. Then measure under comparable local-repository/JDK conditions. A faster RC build that changes artifact metadata is a compatibility finding, not an optimization win.

10. Failure-to-evidence map

Knowledge check

11. Bridge to the checkpoint dossier

Lesson 5 combines these checks into an auditable migration dossier. The output is not “Maven 4 works”; it is a dated decision record containing baseline/candidate identity, compatibility findings, effective-model and artifact comparisons, consumer-POM observations, blockers, release-status assumptions, and exact rollback steps.

Official references and version notes

Version-sensitive statements in this lesson were checked against current Apache Maven primary documentation on 2026-08-24.

• Maven releases history — Current GA and Maven 4 release-candidate status, release dates, and Java requirements.
• What is new in Maven 4 — Java 17 runtime requirement, consumer POM, model 4.1.0 features, BOM packaging, and Maven 4 behavior.
• Starting with Maven 4 — Official prepare → test → migrate strategy, compatibility changes, model 4.1.0 guidance, and rollback-friendly staging.
• Maven Upgrade Tool (mvnup) — Built-in Maven 4 migration tool, check/apply workflow, and 4.0.0 versus 4.1.0 target behavior.
• Maven 4.0.0-rc-6 release notes — Current RC status, migration notes, fixed RC-5 issues, and remaining known issues.
• Apache Maven Wrapper 3.3.4 — Stable wrapper release and integrity-capable wrapper behavior.
• Maven plugin configuration migration notes — Duplicate declarations, removed properties, lifecycle changes, and warning-to-error migration concerns.