This is an automated email from the ASF dual-hosted git repository.

gnodet pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven.git


The following commit(s) were added to refs/heads/master by this push:
     new 2f3947cd0b feat: replace error reference wiki URLs with embedded help 
text (#13944)
2f3947cd0b is described below

commit 2f3947cd0bb4dc8816eee7aaadf04fe11a7f6232
Author: Romain Manni-Bucau <[email protected]>
AuthorDate: Fri Nov 13 09:28:19 2026 +0100

    feat: replace error reference wiki URLs with embedded help text (#13944)
    
    * feat: replace error reference URLs with embedded help text
    
    * perf: avoid reading error help resources unless verbose
    
    Address review feedback on the embedded error help text:
    - add ReferenceHelp.hasHelpText(String) as a cheap existence-only check
      that does not open or read the resource content
    - use hasHelpText() where only the null-check mattered, dropping the
      wasted getResourceAsStream()+readAllBytes() on the error path
    - guard the debug-level help output in MavenCli with isDebugEnabled()
      and in MavenInvoker with effectiveVerbose() so the resource is only
      read when it will actually be logged
    - document the source-breaking logSummary(...) signature change
      (the References collector map parameter was dropped)
    
    * [style] fix spotless check
    
    * fix: handle MojoException (Maven 4 API), UnknownHostException, and dead 
cwiki URLs
    
    - DefaultExceptionHandler.getReference(): extend the MojoExecutionException
      branch to also cover org.apache.maven.api.plugin.MojoException (the Maven 
4
      API equivalent), so plugins using the new API surface get the same 
embedded
      help text as those using the legacy class.
    - Add UnknownHostException detection: when a MojoExecutionException /
      MojoException wraps an IOException whose cause is an UnknownHostException,
      assign the 'UnknownHostException' reference (same pattern as 
ConnectException).
    - Add UnknownHostException.txt help resource explaining hostname resolution
      failures and the -Djava.net.preferIPv4Stack=true workaround.
    - Fix dead cwiki URL generation: only prefix a plain reference key with the 
cwiki
      base URL when ReferenceHelp actually has a resource for that key.  
Unknown or
      third-party noteworthy exceptions previously produced unreachable cwiki 
URLs;
      they now leave the reference as the plain class name, letting 
ReferenceHelp
      correctly return null and produce no output.
    - Update ReferenceHelpTest and DefaultExceptionHandlerTest accordingly.
    
    ---------
    
    Co-authored-by: Guillaume Nodet <[email protected]>
---
 .../main/java/org/apache/maven/cli/MavenCli.java   |  56 ++++----
 .../maven/cling/invoker/mvn/MavenInvoker.java      |  67 +++++-----
 .../maven/exception/DefaultExceptionHandler.java   |   7 +-
 .../apache/maven/exception/ExceptionSummary.java   |   5 +-
 .../org/apache/maven/exception/ReferenceHelp.java  | 127 ++++++++++++++++++
 .../apache/maven/errors/AetherClassNotFound.txt    |  23 ++++
 .../org/apache/maven/errors/ConnectException.txt   |  25 ++++
 .../maven/errors/LifecycleExecutionException.txt   |  24 ++++
 .../org/apache/maven/errors/LinkageError.txt       |  25 ++++
 .../apache/maven/errors/MojoExecutionException.txt |  26 ++++
 .../maven/errors/PluginContainerException.txt      |  26 ++++
 .../maven/errors/PluginExecutionException.txt      |  23 ++++
 .../maven/errors/RemoteRepositoryFiltering.txt     |  26 ++++
 .../apache/maven/errors/UnknownHostException.txt   |  29 +++++
 .../exception/DefaultExceptionHandlerTest.java     |  54 ++++++++
 .../apache/maven/exception/ReferenceHelpTest.java  | 142 +++++++++++++++++++++
 its/core-it-suite/src/site/markdown/index.md.vm    |   2 +-
 .../maven/it/MavenITmng5482AetherNotFoundTest.java |  22 +++-
 ...MavenITmng8469InterpolationPrecendenceTest.java |   2 +-
 19 files changed, 638 insertions(+), 73 deletions(-)

diff --git 
a/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java 
b/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java
index bf18a3e739..a33794173f 100644
--- a/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java
+++ b/compat/maven-embedder/src/main/java/org/apache/maven/cli/MavenCli.java
@@ -38,7 +38,6 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.HashSet;
-import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.ListIterator;
 import java.util.Locale;
@@ -89,6 +88,7 @@
 import org.apache.maven.exception.DefaultExceptionHandler;
 import org.apache.maven.exception.ExceptionHandler;
 import org.apache.maven.exception.ExceptionSummary;
+import org.apache.maven.exception.ReferenceHelp;
 import org.apache.maven.execution.DefaultMavenExecutionRequest;
 import org.apache.maven.execution.ExecutionListener;
 import org.apache.maven.execution.MavenExecutionRequest;
@@ -1111,14 +1111,16 @@ private int execute(CliRequest cliRequest) throws 
MavenExecutionRequestPopulatio
         if (result.hasExceptions()) {
             ExceptionHandler handler = new DefaultExceptionHandler();
 
-            Map<String, String> references = new LinkedHashMap<>();
+            boolean hasDetailedHelp = false;
 
             List<MavenProject> failedProjects = new ArrayList<>();
 
             for (Throwable exception : result.getExceptions()) {
                 ExceptionSummary summary = handler.handleException(exception);
 
-                logSummary(summary, references, "", cliRequest.showErrors);
+                hasDetailedHelp |= 
ReferenceHelp.hasHelpText(summary.getReference());
+
+                logSummary(summary, "", cliRequest.showErrors);
 
                 if (exception instanceof LifecycleExecutionException 
lifecycleExecutionException) {
                     
failedProjects.add(lifecycleExecutionException.getProject());
@@ -1133,18 +1135,14 @@ private int execute(CliRequest cliRequest) throws 
MavenExecutionRequestPopulatio
                         MessageUtils.builder().strong("-e"));
             }
             if (!slf4jLogger.isDebugEnabled()) {
-                slf4jLogger.error(
-                        "Re-run Maven using the '{}' switch to enable verbose 
output",
-                        MessageUtils.builder().strong("-X"));
-            }
-
-            if (!references.isEmpty()) {
-                slf4jLogger.error("");
-                slf4jLogger.error("For more information about the errors and 
possible solutions"
-                        + ", please read the following articles:");
-
-                for (Map.Entry<String, String> entry : references.entrySet()) {
-                    slf4jLogger.error("{} {}", 
MessageUtils.builder().strong(entry.getValue()), entry.getKey());
+                if (hasDetailedHelp) {
+                    slf4jLogger.error(
+                            "Re-run Maven using the '{}' switch to enable full 
debug logging and details about the error",
+                            MessageUtils.builder().strong("-X"));
+                } else {
+                    slf4jLogger.error(
+                            "Re-run Maven using the '{}' switch to enable 
verbose output",
+                            MessageUtils.builder().strong("-X"));
                 }
             }
 
@@ -1211,25 +1209,9 @@ String getResumeFromSelector(List<MavenProject> 
mavenProjects, MavenProject firs
         return ":" + firstFailedProject.getArtifactId();
     }
 
-    private void logSummary(
-            ExceptionSummary summary, Map<String, String> references, String 
indent, boolean showErrors) {
-        String referenceKey = "";
-
-        if (summary.getReference() != null && 
!summary.getReference().isEmpty()) {
-            referenceKey =
-                    references.computeIfAbsent(summary.getReference(), k -> 
"[Help " + (references.size() + 1) + "]");
-        }
-
+    private void logSummary(ExceptionSummary summary, String indent, boolean 
showErrors) {
         String msg = summary.getMessage();
 
-        if (referenceKey != null && !referenceKey.isEmpty()) {
-            if (msg.indexOf('\n') < 0) {
-                msg += " -> " + MessageUtils.builder().strong(referenceKey);
-            } else {
-                msg += "\n-> " + MessageUtils.builder().strong(referenceKey);
-            }
-        }
-
         String[] lines = NEXT_LINE.split(msg);
         String currentColor = "";
 
@@ -1260,10 +1242,18 @@ private void logSummary(
             currentColor = nextColor;
         }
 
+        String reference = summary.getReference();
+        if (reference != null
+                && !reference.isEmpty()
+                && slf4jLogger.isDebugEnabled()
+                && ReferenceHelp.hasHelpText(reference)) {
+            slf4jLogger.debug(ReferenceHelp.getHelpText(reference));
+        }
+
         indent += "  ";
 
         for (ExceptionSummary child : summary.getChildren()) {
-            logSummary(child, references, indent, showErrors);
+            logSummary(child, indent, showErrors);
         }
     }
 
diff --git 
a/impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenInvoker.java
 
b/impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenInvoker.java
index 286cc0804d..f994783d39 100644
--- 
a/impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenInvoker.java
+++ 
b/impl/maven-cli/src/main/java/org/apache/maven/cling/invoker/mvn/MavenInvoker.java
@@ -24,7 +24,6 @@
 import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.IdentityHashMap;
-import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.Optional;
@@ -63,6 +62,7 @@
 import org.apache.maven.exception.DefaultExceptionHandler;
 import org.apache.maven.exception.ExceptionHandler;
 import org.apache.maven.exception.ExceptionSummary;
+import org.apache.maven.exception.ReferenceHelp;
 import org.apache.maven.execution.DefaultMavenExecutionRequest;
 import org.apache.maven.execution.ExecutionListener;
 import org.apache.maven.execution.MavenExecutionRequest;
@@ -567,13 +567,14 @@ protected int doExecute(MavenContext context, 
MavenExecutionRequest request) thr
 
         if (result.hasExceptions()) {
             ExceptionHandler handler = new DefaultExceptionHandler();
-            Map<String, String> references = new LinkedHashMap<>();
+            boolean hasDetailedHelp = false;
             List<MavenProject> failedProjects = new ArrayList<>();
 
             Set<String> hintedArtifacts = new HashSet<>();
             for (Throwable exception : result.getExceptions()) {
                 ExceptionSummary summary = handler.handleException(exception);
-                logSummary(context, summary, references, "");
+                hasDetailedHelp |= 
ReferenceHelp.hasHelpText(summary.getReference());
+                logSummary(context, summary, "");
 
                 if (exception instanceof LifecycleExecutionException 
lifecycleExecutionException) {
                     
failedProjects.add(lifecycleExecutionException.getProject());
@@ -589,17 +590,13 @@ protected int doExecute(MavenContext context, 
MavenExecutionRequest request) thr
                         + MessageUtils.builder().strong("-e") + "' switch");
             }
             if (!context.invokerRequest.effectiveVerbose()) {
-                context.logger.error("Re-run Maven using the '"
-                        + MessageUtils.builder().strong("-X") + "' switch to 
enable verbose output");
-            }
-
-            if (!references.isEmpty()) {
-                context.logger.error("");
-                context.logger.error("For more information about the errors 
and possible solutions"
-                        + ", please read the following articles:");
-
-                for (Map.Entry<String, String> entry : references.entrySet()) {
-                    
context.logger.error(MessageUtils.builder().strong(entry.getValue()) + " " + 
entry.getKey());
+                if (hasDetailedHelp) {
+                    context.logger.error("Re-run Maven using the '"
+                            + MessageUtils.builder().strong("-X")
+                            + "' switch to enable full debug logging and 
details about the error");
+                } else {
+                    context.logger.error("Re-run Maven using the '"
+                            + MessageUtils.builder().strong("-X") + "' switch 
to enable verbose output");
                 }
             }
 
@@ -734,25 +731,23 @@ protected String getResumeFromSelector(List<MavenProject> 
mavenProjects, MavenPr
 
     protected static final String ANSI_RESET = "\u001B\u005Bm";
 
-    protected void logSummary(
-            MavenContext context, ExceptionSummary summary, Map<String, 
String> references, String indent) {
-        String referenceKey = "";
-
-        if (summary.getReference() != null && 
!summary.getReference().isEmpty()) {
-            referenceKey =
-                    references.computeIfAbsent(summary.getReference(), k -> 
"[Help " + (references.size() + 1) + "]");
-        }
-
+    /**
+     * Logs the summary of a failed build, including any embedded detailed 
help text associated with
+     * {@link ExceptionSummary#getReference()} when verbose output is enabled.
+     * <p>
+     * Migration note: the former {@code logSummary(MavenContext, 
ExceptionSummary, Map<String, String>,
+     * String)} overload (which collected the reference URLs into a {@code 
references} map) was replaced by
+     * this three-argument form. The collector map has been dropped: detailed 
help is now read on demand from
+     * the {@link ReferenceHelp} resources instead. Subclasses overriding the 
old overload must update to this
+     * signature.
+     *
+     * @param context the Maven context used for logging
+     * @param summary the exception summary to log
+     * @param indent the indentation prefix for nested summary lines
+     */
+    protected void logSummary(MavenContext context, ExceptionSummary summary, 
String indent) {
         String msg = summary.getMessage();
 
-        if (!referenceKey.isEmpty()) {
-            if (msg.indexOf('\n') < 0) {
-                msg += " -> " + MessageUtils.builder().strong(referenceKey);
-            } else {
-                msg += "\n-> " + MessageUtils.builder().strong(referenceKey);
-            }
-        }
-
         String[] lines = NEXT_LINE.split(msg);
         String currentColor = "";
 
@@ -785,10 +780,18 @@ protected void logSummary(
             currentColor = nextColor;
         }
 
+        String reference = summary.getReference();
+        if (reference != null
+                && !reference.isEmpty()
+                && context.invokerRequest.effectiveVerbose()
+                && ReferenceHelp.hasHelpText(reference)) {
+            context.logger.debug(ReferenceHelp.getHelpText(reference));
+        }
+
         indent += "  ";
 
         for (ExceptionSummary child : summary.getChildren()) {
-            logSummary(context, child, references, indent);
+            logSummary(context, child, indent);
         }
     }
 }
diff --git 
a/impl/maven-core/src/main/java/org/apache/maven/exception/DefaultExceptionHandler.java
 
b/impl/maven-core/src/main/java/org/apache/maven/exception/DefaultExceptionHandler.java
index 8bd38b6176..a7f518d9d7 100644
--- 
a/impl/maven-core/src/main/java/org/apache/maven/exception/DefaultExceptionHandler.java
+++ 
b/impl/maven-core/src/main/java/org/apache/maven/exception/DefaultExceptionHandler.java
@@ -169,7 +169,7 @@ private String getReference(Set<Throwable> dejaVu, 
Throwable exception) {
         }
 
         if (exception != null) {
-            if (exception instanceof MojoExecutionException) {
+            if (exception instanceof MojoExecutionException || exception 
instanceof MojoException) {
                 reference = MojoExecutionException.class.getSimpleName();
 
                 Throwable cause = exception.getCause();
@@ -177,6 +177,8 @@ private String getReference(Set<Throwable> dejaVu, 
Throwable exception) {
                     cause = cause.getCause();
                     if (cause instanceof ConnectException) {
                         reference = ConnectException.class.getSimpleName();
+                    } else if (cause instanceof UnknownHostException) {
+                        reference = UnknownHostException.class.getSimpleName();
                     }
                 }
                 if (findCause(exception, ArtifactFilteredOutException.class) 
!= null) {
@@ -214,7 +216,8 @@ private String getReference(Set<Throwable> dejaVu, 
Throwable exception) {
 
         if ((reference != null && !reference.isEmpty())
                 && !reference.startsWith("http:")
-                && !reference.startsWith("https:")) {
+                && !reference.startsWith("https:")
+                && ReferenceHelp.hasHelpText(reference)) {
             reference = "http://cwiki.apache.org/confluence/display/MAVEN/"; + 
reference;
         }
 
diff --git 
a/impl/maven-core/src/main/java/org/apache/maven/exception/ExceptionSummary.java
 
b/impl/maven-core/src/main/java/org/apache/maven/exception/ExceptionSummary.java
index 7473e380a2..15f76622b2 100644
--- 
a/impl/maven-core/src/main/java/org/apache/maven/exception/ExceptionSummary.java
+++ 
b/impl/maven-core/src/main/java/org/apache/maven/exception/ExceptionSummary.java
@@ -25,9 +25,8 @@
  * Provide a summary of the exception, containing:<ul>
  * <li>the exception itself,</li>
  * <li>useful end-user message,</li>
- * <li>useful reference to a solution, or set of solutions: this is usually a 
wiki page url in
- * <a 
href="http://cwiki.apache.org/confluence/display/MAVEN/";>http://cwiki.apache.org/confluence/display/MAVEN/</a>,
- * </li>
+ * <li>reference identifying the error kind, used to look up detailed help 
text (see
+ * {@link ReferenceHelp}),</li>
  * <li>child exception summaries.</li>
  * </ul>
  */
diff --git 
a/impl/maven-core/src/main/java/org/apache/maven/exception/ReferenceHelp.java 
b/impl/maven-core/src/main/java/org/apache/maven/exception/ReferenceHelp.java
new file mode 100644
index 0000000000..7caa5d2b07
--- /dev/null
+++ 
b/impl/maven-core/src/main/java/org/apache/maven/exception/ReferenceHelp.java
@@ -0,0 +1,127 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.exception;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
+
+/**
+ * Resolves the user-friendly help text associated with an {@link 
ExceptionSummary} reference.
+ * <p>
+ * Help text is stored as text resources in {@code org/apache/maven/errors/} 
of {@code maven-core}, one file per
+ * reference key (for example {@code AetherClassNotFound.txt}). Unknown or 
third-party references for which no
+ * resource exists resolve to {@code null} and produce no output.
+ */
+public final class ReferenceHelp {
+
+    private static final String RESOURCE_PREFIX = "/org/apache/maven/errors/";
+    private static final String CWIKI_PREFIX = 
"http://cwiki.apache.org/confluence/display/MAVEN/";;
+    private static final String RRF_URL = 
"https://maven.apache.org/resolver/remote-repository-filtering.html";;
+
+    private ReferenceHelp() {}
+
+    /**
+     * Returns the help text associated with the given exception reference 
(either a plain key such as
+     * {@code AetherClassNotFound} or a classic wiki URL such as
+     * {@code 
http://cwiki.apache.org/confluence/display/MAVEN/AetherClassNotFound}), or 
{@code null}
+     * when no help text is available for this reference.
+     *
+     * @param reference the exception reference, may be {@code null} or empty
+     * @return the help text, or {@code null} when none is available
+     */
+    public static String getHelpText(String reference) {
+        String key = normalizeKey(reference);
+        if (key == null) {
+            return null;
+        }
+        try (InputStream in = 
ReferenceHelp.class.getResourceAsStream(RESOURCE_PREFIX + key + ".txt")) {
+            if (in == null) {
+                return null;
+            }
+            String content = new String(in.readAllBytes(), 
StandardCharsets.UTF_8);
+            // resources carry an Apache license header as '#' comments; strip 
it before returning
+            StringBuilder text = new StringBuilder();
+            boolean headerDone = false;
+            for (String line : content.split("\r?\n", -1)) {
+                if (!headerDone && line.startsWith("#")) {
+                    continue;
+                }
+                headerDone = true;
+                text.append(line).append('\n');
+            }
+            return text.toString().strip();
+        } catch (IOException e) {
+            return null;
+        }
+    }
+
+    /**
+     * Returns whether a help text resource exists for the given exception 
reference. This is a cheap
+     * existence-only check that does not read the resource content; use it 
when only knowing whether a
+     * reference is backed by help text matters (for example to decide whether 
to hint at the verbose
+     * {@code -X} switch), and call {@link #getHelpText(String)} only when the 
text is actually needed.
+     *
+     * @param reference the exception reference, may be {@code null} or empty
+     * @return {@code true} when a help text resource exists for the 
reference, {@code false} otherwise
+     */
+    public static boolean hasHelpText(String reference) {
+        String key = normalizeKey(reference);
+        return key != null && ReferenceHelp.class.getResource(RESOURCE_PREFIX 
+ key + ".txt") != null;
+    }
+
+    /**
+     * Extracts the resource key from a reference (plain key or wiki URL) and 
validates it is safe to use
+     * as a file name. Returns {@code null} when the reference cannot be 
mapped to a resource.
+     */
+    static String normalizeKey(String reference) {
+        if (reference == null || reference.isEmpty()) {
+            return null;
+        }
+        String key = reference;
+        if (key.startsWith(CWIKI_PREFIX)) {
+            key = key.substring(CWIKI_PREFIX.length());
+        } else if (RRF_URL.equals(key)) {
+            key = "RemoteRepositoryFiltering";
+        } else if (key.startsWith("http://";) || key.startsWith("https://";)) {
+            int slash = key.lastIndexOf('/');
+            if (slash < 0) {
+                return null;
+            }
+            key = key.substring(slash + 1);
+        } else if (key.indexOf('/') >= 0) {
+            // a plain key must not be a path
+            return null;
+        }
+        int query = key.indexOf('?');
+        if (query >= 0) {
+            key = key.substring(0, query);
+        }
+        if (key.isEmpty()) {
+            return null;
+        }
+        for (int i = 0; i < key.length(); i++) {
+            char c = key.charAt(i);
+            if (!(Character.isLetterOrDigit(c) || c == '_' || c == '-')) {
+                return null;
+            }
+        }
+        return key;
+    }
+}
diff --git 
a/impl/maven-core/src/main/resources/org/apache/maven/errors/AetherClassNotFound.txt
 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/AetherClassNotFound.txt
new file mode 100644
index 0000000000..bd10fb305e
--- /dev/null
+++ 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/AetherClassNotFound.txt
@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+A plugin uses the old Sonatype Aether API (org.sonatype.aether.*), which Maven
+replaced with Eclipse Aether / Maven Resolver many releases ago.
+
+Plugins that still depend on org/sonatype/aether classes cannot run on modern
+Maven versions. Upgrade the plugin to a version compatible with the Maven
+version you use; the plugin index at 
https://maven.apache.org/plugins/index.html
+lists the current releases of the common plugins.
diff --git 
a/impl/maven-core/src/main/resources/org/apache/maven/errors/ConnectException.txt
 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/ConnectException.txt
new file mode 100644
index 0000000000..83389f2d69
--- /dev/null
+++ 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/ConnectException.txt
@@ -0,0 +1,25 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+Maven could not connect to a remote host.
+
+This often happens when Java prefers IPv6 while the host or the network only
+supports IPv4. If the stack trace shows a "Connection refused" while 
establishing
+a loopback connection, force Java to use IPv4 with:
+
+  -Djava.net.preferIPv4Stack=true
+
+Add this option to MAVEN_OPTS to apply it to all Maven commands.
diff --git 
a/impl/maven-core/src/main/resources/org/apache/maven/errors/LifecycleExecutionException.txt
 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/LifecycleExecutionException.txt
new file mode 100644
index 0000000000..b5e6cf9868
--- /dev/null
+++ 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/LifecycleExecutionException.txt
@@ -0,0 +1,24 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+A lifecycle phase could not complete because one of its bound plugin goals
+failed, or because Maven could not build the project model (for example when a
+parent POM or one of its modules cannot be read).
+
+Look at the "Caused by" entries of the stack trace (re-run with -e to see the
+full trace) to find the underlying failure, then fix that root cause: plugin
+execution errors are usually reported against the exact goal and project that
+failed.
diff --git 
a/impl/maven-core/src/main/resources/org/apache/maven/errors/LinkageError.txt 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/LinkageError.txt
new file mode 100644
index 0000000000..70f5b8f11b
--- /dev/null
+++ 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/LinkageError.txt
@@ -0,0 +1,25 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+A plugin or extension could not be loaded because of incompatible or 
conflicting
+classes on its class path.
+
+This usually happens when a plugin (or one of its dependencies) was built 
against
+a different version of a library than the one resolved at build time, or when 
the
+plugin is not compatible with the Maven version in use. Check the versions of 
the
+plugin and of the dependencies it declares, and align them with the ones the
+plugin requires. Upgrading the plugin, or explicitly aligning the conflicting
+dependency versions, typically fixes the problem.
diff --git 
a/impl/maven-core/src/main/resources/org/apache/maven/errors/MojoExecutionException.txt
 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/MojoExecutionException.txt
new file mode 100644
index 0000000000..4222f35e58
--- /dev/null
+++ 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/MojoExecutionException.txt
@@ -0,0 +1,26 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+A plugin failed to execute its goal.
+
+This error usually comes from the plugin itself: its configuration is invalid, 
or
+the information it read from the POM is not what it expects. The exact meaning
+depends on the plugin, so consult the plugin documentation (most are listed on
+https://maven.apache.org/plugins/index.html) and the goal that failed.
+
+If the failure involves network access (download or upload of artifacts), check
+your network connection, your proxy configuration, and the repositories 
declared
+in the POM or in your settings.xml.
diff --git 
a/impl/maven-core/src/main/resources/org/apache/maven/errors/PluginContainerException.txt
 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/PluginContainerException.txt
new file mode 100644
index 0000000000..bc75989577
--- /dev/null
+++ 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/PluginContainerException.txt
@@ -0,0 +1,26 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+Maven could not load a goal from its plugin class path.
+
+Possible causes:
+- the plugin JAR or POM (or one of its dependencies) was corrupted while being
+  downloaded; delete the affected files from your local repository (usually
+  ~/.m2/repository) and let Maven re-download them
+- custom plugin dependencies declared in your POM are not compatible with the
+  plugin; align their versions with the ones the plugin natively uses
+- the plugin was not assembled properly by its creator; report the problem to
+  the plugin maintainer
diff --git 
a/impl/maven-core/src/main/resources/org/apache/maven/errors/PluginExecutionException.txt
 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/PluginExecutionException.txt
new file mode 100644
index 0000000000..8cd477d005
--- /dev/null
+++ 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/PluginExecutionException.txt
@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+Execution of a plugin failed because of an unforeseen error, for example an
+uncaught runtime exception thrown by the plugin itself.
+
+Look at the stack trace to find the root cause: it may point to a bug in the
+plugin, to an incompatible configuration, or to a problem in the project. If 
the
+failure comes from the plugin code, report the problem to the plugin maintainer
+and include the full stack trace (re-run with -e to get it).
diff --git 
a/impl/maven-core/src/main/resources/org/apache/maven/errors/RemoteRepositoryFiltering.txt
 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/RemoteRepositoryFiltering.txt
new file mode 100644
index 0000000000..c9401e537a
--- /dev/null
+++ 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/RemoteRepositoryFiltering.txt
@@ -0,0 +1,26 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+Maven could not download an artifact because a remote repository filter 
rejected
+the request.
+
+Repository filters are usually configured through the 
-Daether.remoteRepositoryFilter.*
+system properties (for example -Daether.remoteRepositoryFilter.prefixes=false 
or
+-Daether.remoteRepositoryFilter.groupId=false) or in settings.xml. Adjust the
+filter so that the artifact is allowed, or remove it if it is too restrictive.
+
+Full documentation:
+https://maven.apache.org/resolver/remote-repository-filtering.html
diff --git 
a/impl/maven-core/src/main/resources/org/apache/maven/errors/UnknownHostException.txt
 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/UnknownHostException.txt
new file mode 100644
index 0000000000..6e612e3341
--- /dev/null
+++ 
b/impl/maven-core/src/main/resources/org/apache/maven/errors/UnknownHostException.txt
@@ -0,0 +1,29 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+Maven could not resolve a remote hostname.
+
+This usually means the host name in a repository URL is wrong or unreachable:
+- Check that the repository URL in your POM or settings.xml is correct.
+- Verify that your machine can reach the host (e.g. try pinging it or opening 
the
+  URL in a browser).
+- If you are behind a corporate proxy, make sure the proxy is configured in
+  ~/.m2/settings.xml under <proxies>.
+- On some networks, IPv6 DNS resolution fails while IPv4 works; force IPv4 
with:
+
+    -Djava.net.preferIPv4Stack=true
+
+  Add this option to MAVEN_OPTS to apply it to all Maven commands.
diff --git 
a/impl/maven-core/src/test/java/org/apache/maven/exception/DefaultExceptionHandlerTest.java
 
b/impl/maven-core/src/test/java/org/apache/maven/exception/DefaultExceptionHandlerTest.java
index 2ea55f64b5..3d305d0c14 100644
--- 
a/impl/maven-core/src/test/java/org/apache/maven/exception/DefaultExceptionHandlerTest.java
+++ 
b/impl/maven-core/src/test/java/org/apache/maven/exception/DefaultExceptionHandlerTest.java
@@ -21,9 +21,11 @@
 import java.io.File;
 import java.io.IOException;
 import java.net.ConnectException;
+import java.net.UnknownHostException;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicReference;
 
+import org.apache.maven.api.plugin.MojoException;
 import org.apache.maven.model.Plugin;
 import org.apache.maven.model.building.DefaultModelProblem;
 import org.apache.maven.model.building.ModelProblem;
@@ -236,6 +238,58 @@ void testProjectBuildingExceptionNotRenderedTwice() {
         assertEquals(1, countOccurrences(flatten(summary), "Malformed POM 
test.xml: unexpected element"));
     }
 
+    @Test
+    void testHandleExceptionUnknownHost() {
+        UnknownHostException unknownHostEx = new 
UnknownHostException("repo.example.com");
+        IOException ioEx = new IOException("repo.example.com", unknownHostEx);
+        MojoExecutionException mojoEx = new MojoExecutionException("Could not 
transfer artifact", ioEx);
+
+        ExceptionHandler exceptionHandler = new DefaultExceptionHandler();
+        ExceptionSummary exceptionSummary = 
exceptionHandler.handleException(mojoEx);
+
+        String expectedReference = 
"http://cwiki.apache.org/confluence/display/MAVEN/UnknownHostException";;
+        assertEquals(expectedReference, exceptionSummary.getReference());
+    }
+
+    @Test
+    void testHandleExceptionMojoException() {
+        MojoException mojoEx = new MojoException("Plugin goal failed: invalid 
configuration");
+
+        ExceptionHandler exceptionHandler = new DefaultExceptionHandler();
+        ExceptionSummary exceptionSummary = 
exceptionHandler.handleException(mojoEx);
+
+        String expectedReference = 
"http://cwiki.apache.org/confluence/display/MAVEN/MojoExecutionException";;
+        assertEquals(expectedReference, exceptionSummary.getReference());
+    }
+
+    @Test
+    void testHandleExceptionMojoExceptionWithUnknownHost() {
+        UnknownHostException unknownHostEx = new 
UnknownHostException("repo.example.com");
+        IOException ioEx = new IOException("repo.example.com", unknownHostEx);
+        MojoException mojoEx = new MojoException("Could not transfer 
artifact", ioEx);
+
+        ExceptionHandler exceptionHandler = new DefaultExceptionHandler();
+        ExceptionSummary exceptionSummary = 
exceptionHandler.handleException(mojoEx);
+
+        String expectedReference = 
"http://cwiki.apache.org/confluence/display/MAVEN/UnknownHostException";;
+        assertEquals(expectedReference, exceptionSummary.getReference());
+    }
+
+    @Test
+    void testUnknownNoteworthyExceptionProducesNoDeadCwikiUrl() {
+        // A noteworthy exception with no help text resource should NOT 
produce a cwiki URL
+        IOException ioEx = new IOException("some unknown checked exception");
+
+        ExceptionHandler exceptionHandler = new DefaultExceptionHandler();
+        ExceptionSummary exceptionSummary = 
exceptionHandler.handleException(ioEx);
+
+        String reference = exceptionSummary.getReference();
+        // must not be a dead cwiki URL
+        assertTrue(
+                reference == null || reference.isEmpty() || 
!reference.startsWith("http://cwiki";),
+                "Unknown noteworthy exception should not produce a dead cwiki 
URL, got: " + reference);
+    }
+
     private static String flatten(ExceptionSummary summary) {
         if (summary == null) {
             return "";
diff --git 
a/impl/maven-core/src/test/java/org/apache/maven/exception/ReferenceHelpTest.java
 
b/impl/maven-core/src/test/java/org/apache/maven/exception/ReferenceHelpTest.java
new file mode 100644
index 0000000000..421e46661f
--- /dev/null
+++ 
b/impl/maven-core/src/test/java/org/apache/maven/exception/ReferenceHelpTest.java
@@ -0,0 +1,142 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.maven.exception;
+
+import java.util.List;
+
+import org.junit.jupiter.api.Test;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertNotNull;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class ReferenceHelpTest {
+
+    private static final List<String> BUILT_IN_KEYS = List.of(
+            "MojoExecutionException",
+            "ConnectException",
+            "UnknownHostException",
+            "LinkageError",
+            "PluginExecutionException",
+            "AetherClassNotFound",
+            "PluginContainerException",
+            "LifecycleExecutionException",
+            "RemoteRepositoryFiltering");
+
+    @Test
+    void normalizeKeyHandlesPlainKeys() {
+        assertEquals("AetherClassNotFound", 
ReferenceHelp.normalizeKey("AetherClassNotFound"));
+    }
+
+    @Test
+    void normalizeKeyHandlesCwikiUrls() {
+        assertEquals(
+                "AetherClassNotFound",
+                
ReferenceHelp.normalizeKey("http://cwiki.apache.org/confluence/display/MAVEN/AetherClassNotFound";));
+    }
+
+    @Test
+    void normalizeKeyHandlesArbitraryUrls() {
+        assertEquals(
+                "AetherClassNotFound",
+                
ReferenceHelp.normalizeKey("https://maven.apache.org/resolver/AetherClassNotFound";));
+        assertEquals("MyError", 
ReferenceHelp.normalizeKey("https://example.com/errors/MyError?x=1";));
+    }
+
+    @Test
+    void normalizeKeyRejectsInvalidKeys() {
+        assertNull(ReferenceHelp.normalizeKey(null));
+        assertNull(ReferenceHelp.normalizeKey(""));
+        
assertNull(ReferenceHelp.normalizeKey("http://cwiki.apache.org/confluence/display/MAVEN/";));
+        assertNull(ReferenceHelp.normalizeKey("a/b"));
+        assertNull(ReferenceHelp.normalizeKey("a b"));
+    }
+
+    @Test
+    void everyBuiltInReferenceHasHelpText() {
+        for (String key : BUILT_IN_KEYS) {
+            String help = ReferenceHelp.getHelpText(key);
+            assertNotNull(help, "Expected help text for " + key);
+            assertTrue(!help.isBlank(), "Expected non-blank help text for " + 
key);
+        }
+    }
+
+    @Test
+    void cwikiStyleReferencesResolveToSameHelpText() {
+        for (String key : BUILT_IN_KEYS) {
+            String plain = ReferenceHelp.getHelpText(key);
+            String url = 
ReferenceHelp.getHelpText("http://cwiki.apache.org/confluence/display/MAVEN/"; + 
key);
+            assertEquals(plain, url, "Help text should not depend on reference 
form for " + key);
+        }
+    }
+
+    @Test
+    void unknownReferencesProduceNoHelpText() {
+        assertNull(ReferenceHelp.getHelpText("NoSuchException"));
+        assertNull(ReferenceHelp.getHelpText("com.example.SomeError"));
+        assertNull(ReferenceHelp.getHelpText(""));
+        assertNull(ReferenceHelp.getHelpText(null));
+    }
+
+    @Test
+    void hasHelpTextReturnsTrueForBuiltInReferences() {
+        for (String key : BUILT_IN_KEYS) {
+            assertTrue(ReferenceHelp.hasHelpText(key), "Expected help text 
resource for " + key);
+            assertTrue(
+                    
ReferenceHelp.hasHelpText("http://cwiki.apache.org/confluence/display/MAVEN/"; + 
key),
+                    "Expected help text resource for cwiki URL of " + key);
+        }
+        
assertTrue(ReferenceHelp.hasHelpText("https://maven.apache.org/resolver/remote-repository-filtering.html";));
+    }
+
+    @Test
+    void hasHelpTextReturnsFalseForUnknownOrInvalidReferences() {
+        assertFalse(ReferenceHelp.hasHelpText("NoSuchException"));
+        assertFalse(ReferenceHelp.hasHelpText("com.example.SomeError"));
+        assertFalse(ReferenceHelp.hasHelpText("a b"));
+        assertFalse(ReferenceHelp.hasHelpText(""));
+        assertFalse(ReferenceHelp.hasHelpText(null));
+    }
+
+    @Test
+    void hasHelpTextAgreesWithGetHelpTextForBuiltIns() {
+        for (String key : BUILT_IN_KEYS) {
+            assertEquals(ReferenceHelp.getHelpText(key) != null, 
ReferenceHelp.hasHelpText(key), key);
+        }
+    }
+
+    @Test
+    void helpTextIsTrimmed() {
+        String help = ReferenceHelp.getHelpText("AetherClassNotFound");
+        assertNotNull(help);
+        assertEquals(help, help.strip());
+        assertTrue(help.contains("Sonatype Aether"), "Help text should mention 
Sonatype Aether");
+    }
+
+    @Test
+    void remoteRepositoryFilteringUrlResolvesToHelpText() {
+        String help = 
ReferenceHelp.getHelpText("https://maven.apache.org/resolver/remote-repository-filtering.html";);
+        assertNotNull(help);
+        assertTrue(
+                
help.contains("https://maven.apache.org/resolver/remote-repository-filtering.html";),
+                "Help text should reference the remote repository filtering 
documentation");
+    }
+}
diff --git a/its/core-it-suite/src/site/markdown/index.md.vm 
b/its/core-it-suite/src/site/markdown/index.md.vm
index eb69b366f5..def160d902 100644
--- a/its/core-it-suite/src/site/markdown/index.md.vm
+++ b/its/core-it-suite/src/site/markdown/index.md.vm
@@ -58,7 +58,7 @@ So some care needs to be taken when introducing new 
dependencies into the ITs th
 ```
 [ERROR] testit(org.apache.maven.it.MavenITmng...)  Time elapsed: 0.145 s  <<< 
ERROR!
 ...
-[ERROR] Failed to execute goal ... (...) on project ...: ... Could not find 
artifact ... in central (file:target/null) -> [Help 1]
+[ERROR] Failed to execute goal ... (...) on project ...: ... Could not find 
artifact ... in central (file:target/null)
 ```
 
 #[[### Using Local Repository Manager]]#
diff --git 
a/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng5482AetherNotFoundTest.java
 
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng5482AetherNotFoundTest.java
index 8974554031..ed34523a47 100644
--- 
a/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng5482AetherNotFoundTest.java
+++ 
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng5482AetherNotFoundTest.java
@@ -68,8 +68,28 @@ public void check(String dir) throws IOException, 
VerificationException {
         int msg = indexOf(lines, "Caused by: java.lang.ClassNotFoundException: 
org.sonatype.aether.+");
         assertTrue(msg >= 0, "ClassNotFoundException message was not found in 
output.");
 
+        // the legacy wiki URL is no longer printed on standard output
         int url = indexOf(lines, 
".*http://cwiki.apache.org/confluence/display/MAVEN/AetherClassNotFound.*";);
-        assertTrue(url >= 0, "Url to ClassNotFoundAether was not found in 
output.");
+        assertTrue(url < 0, "Url to ClassNotFoundAether should not be found in 
output.");
+
+        // the -X hint is shown, since detailed help is available for this 
error
+        int hint =
+                indexOf(lines, ".*switch to enable full debug logging and 
details about the error.*");
+        assertTrue(hint >= 0, "-X hint was not found in output.");
+
+        // with -X, the dedicated help text is logged
+        Verifier debugVerifier = newVerifier(testDir);
+        debugVerifier.setAutoclean(false);
+
+        debugVerifier.addCliArgument("validate");
+        debugVerifier.addCliArgument("-X");
+        assertThrows(
+                VerificationException.class, debugVerifier::execute, "should 
throw an error during execution.");
+
+        List<String> debugLines = 
debugVerifier.loadFile(testDir.resolve("log.txt"));
+
+        int help = indexOf(debugLines, ".*Sonatype Aether.*");
+        assertTrue(help >= 0, "AetherClassNotFound help text was not found in 
debug output.");
     }
 
     private int indexOf(List<String> logLines, String regex) {
diff --git 
a/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng8469InterpolationPrecendenceTest.java
 
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng8469InterpolationPrecendenceTest.java
index 93bf8276d6..ba6692f73c 100644
--- 
a/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng8469InterpolationPrecendenceTest.java
+++ 
b/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng8469InterpolationPrecendenceTest.java
@@ -43,7 +43,7 @@ void testIt() throws Exception {
 
         // 4.0.0-rc-2 fails as
         // [ERROR] Some problems were encountered while processing the POMs
-        // [ERROR] The build could not read 1 project -> [Help 1]
+        // [ERROR] The build could not read 1 project
         // [ERROR]
         // [ERROR]   The project org.apache.maven.its.mng8469:test:1.0 
(...pom.xml) has 1 error
         // [ERROR]     recursive variable reference: scm.connection

Reply via email to