Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 41 ยท Alternatives and Migration

Troubleshooting Common Maven Errors

Read Maven failures like a pro: wrong Java version, missing dependencies, plugin not found, stale cache, certificate, proxy and out-of-memory errors, with fixes.

Most Maven errors look alarming and mean something small. A wall of red text usually boils down to one line, and that line usually names one of about a dozen causes: the wrong JDK, a dependency Maven cannot find, a plugin it cannot load, a cached failure, or a network that interferes with HTTPS. Learn the dozen and you will fix most failures in a minute.

This lesson teaches you to find the line that matters, then walks through the common errors with their causes and fixes. Maven cannot run on this site, so the commands and logs are read-only text. The TryIts are stand-ins: a rule-based diagnoser that matches log lines to causes, and a Java-version checker.

Read the error in four steps

Find the first ERROR Later lines are usually fallout.
Name the goal Which plugin goal and which module failed?
Read the cause The text after the last colon is the clue.
Rerun with more detail Add -e, -X or -U as needed.
1 / 2

Anatomy of a failure

Every failed build ends with a block like this:

TEXT
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile
  (default-compile) on project textkit: Fatal error compiling: error: release version 21
  not supported -> [Help 1]

Read it from left to right. maven-compiler-plugin:3.13.0:compile is the plugin and goal that failed, default-compile is the execution, on project textkit is the module (important in a multi-module build, because the reactor stops at the first failure), and everything after the final colon is the real message. Maven prints [Help 1] as a pointer to its wiki page. You can ignore it.

Rerun with extra detail only when the message is not enough.

Terminal
mvn -e verify      # show the full stack trace of the failure
mvn -X verify      # debug logging: classpath, plugin config, resolution details
mvn -U verify      # force a re-check of SNAPSHOTs and previously failed lookups
mvn -rf :service verify   # resume the reactor from one module after you fixed it

-X output is huge. Redirect it to a file (mvn -X verify > build.log) and search for the module name or the first ERROR.

The Java version family

release version 21 not supported (older plugin versions say invalid target release: 21). The JDK that runs Maven is older than the release you asked for. Run mvn -v: it prints the Java version Maven actually uses, which may differ from java -version in another terminal. Fix JAVA_HOME, install a newer JDK, or lower maven.compiler.release. See Installing Maven and the Wrapper and Properties and Build Settings.

No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK? JAVA_HOME points at a runtime without javac. Point it at a full JDK.

The JAVA_HOME environment variable is not defined correctly. The folder in JAVA_HOME does not exist or does not contain bin/java. Point it at the JDK's top folder, not at its bin directory.

Unsupported class file major version 69. A tool (often an old plugin that bundles a bytecode library) is reading classes compiled by a newer JDK than it understands. Class-file major numbers are 44 plus the Java version, so 69 means Java 25. Upgrade the plugin that prints the error. This is the opposite problem to the first one: there the compiler is too old, here the tool is too old.

The dependency family

Could not find artifact com.example:foo:jar:1.0 in central (https://repo.maven.apache.org/maven2). The artifact is in none of your repositories. In order of likelihood: a typo in the coordinates, a version that was never published, a private artifact whose repository is missing from the POM or settings.xml, or a library you meant to mvn install locally first. Search Maven Central for the exact groupId and artifactId.

Failure to find ... was cached in the local repository, resolution will not be reattempted until the update interval of central has elapsed or updates are forced. Maven remembers failed lookups (as *.lastUpdated files in ~/.m2/repository) so it does not hammer a server. After you fix the real cause, run mvn -U once. If a download was corrupted halfway, delete just that artifact's folder under ~/.m2/repository rather than the whole cache. See Repositories and the Local Cache.

Non-resolvable parent POM. The <parent> cannot be found where relativePath points or in a repository. Check the parent's coordinates and that the folder layout matches relativePath (see Parent POMs and the Effective POM).

NoSuchMethodError or ClassNotFoundException at run time. Not a build error but a conflict: two versions of a library compete. Use mvn dependency:tree -Dverbose, as in Diagnosing Dependency Conflicts.

The plugin family

No plugin found for prefix 'foo' in the current project and in the plugin groups. You typed mvn foo:bar but Maven cannot map foo to a plugin. Either the prefix has a typo, or the plugin is not declared and is not in an official group. Use the full form: mvn org.example:foo-maven-plugin:1.2.0:bar.

Plugin ... or one of its dependencies could not be resolved. Same causes as a missing dependency, but for plugins, which come from plugin repositories. Check the version and your mirror configuration.

Unknown lifecycle phase "compil". A typo in the phase name. Valid phases are listed in Lifecycles and Phases.

The network family

PKIX path building failed: ... unable to find valid certification path to requested target. Java does not trust the certificate that answered. This typically happens behind a company proxy that re-signs HTTPS traffic. The right fix is to import your organization's root certificate into the JDK's truststore (or point -Djavax.net.ssl.trustStore at a store that has it). Do not "fix" it by disabling certificate checks: that removes the protection against a tampered download.

Could not transfer artifact ... Connect timed out or 407 Proxy Authentication Required. Configure the <proxies> and <mirrors> sections of settings.xml, as in settings.xml, Mirrors and Credentials. A 401 or 403 from a private repository means missing or wrong <server> credentials, or a <server><id> that does not match the repository id.

Memory and tests

java.lang.OutOfMemoryError: Java heap space. If the stack comes from Maven itself, give Maven more heap: set MAVEN_OPTS=-Xmx2g or put -Xmx2g in .mvn/jvm.config, which travels with the repository. If it comes from your tests, the memory limit belongs to the forked test JVM, so configure it with <argLine>-Xmx1g</argLine> in Surefire instead.

There are test failures. Maven is fine; your tests are not. Read target/surefire-reports/. To get the build moving temporarily, use -DskipTests (compile tests, skip running them), but do not commit that to the POM.

A diagnoser you can run

The first TryIt is a stand-in for the little table in your head: it holds the rules above as regular expressions and prints the cause and the fix for each log line. The real Maven prints far more, but the principle holds: match a known phrase, name the cause.

Java A rule-based log diagnoser

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Checking the Java version

The most common first-day failure is a Java mismatch. The compiler plugin passes --release N to javac, which needs a JDK of at least that feature version (and at least JDK 9 to understand the flag at all). Very old targets are eventually dropped by newer JDKs. This stand-in encodes those three rules and also prints the class-file major number your output would have.

Java Does this JDK accept this release?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

When you see a failure you cannot place, follow the escalation ladder: read the first ERROR, run mvn -v, run mvn help:effective-pom to see the real configuration, run mvn -e, and only then mvn -X. Searching for the exact message plus the plugin version usually finds the answer within minutes.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Maven reports 'release version 21 not supported'. What should you check first?

    mvn -v shows which JDK Maven really runs with. If it is older than maven.compiler.release, the compiler cannot produce that bytecode level.
  2. 2. A dependency lookup failed yesterday, you fixed the repository today, but Maven still refuses. What helps?

    Maven caches failed lookups. -U forces it to re-check instead of waiting for the update interval.
  3. 3. You see 'PKIX path building failed' behind a corporate proxy. What is the correct fix?

    The JVM does not trust the certificate presented by the proxy. Trusting the right root certificate keeps HTTPS protection intact, unlike disabling checks.
  4. 4. 'Unsupported class file major version 69' appears from an old plugin. What does it mean?

    Major version 69 is Java 25 (44 plus 25). A tool bundling an outdated bytecode reader cannot parse it; upgrading the plugin fixes it.
  5. 5. Where should the memory limit for tests that run out of heap be configured?

    Surefire forks a separate JVM for tests. MAVEN_OPTS affects Maven's own JVM, not the forked one.

Summary

  • Find the first ERROR, then read the plugin goal, the module and the text after the final colon.
  • Use -e for stack traces, -X for debug output, -U to retry cached failures and -rf to resume a reactor.
  • Most failures fall into four families: Java version, dependency, plugin and network.
  • Fix certificate errors by trusting the right certificate, never by turning verification off.
  • The diagnoser and version checker here are stand-ins that model the rules, not Maven itself.

Now put the pieces together in a complete build: Project: A Reusable Library.