Skip to content
javahacks.dev
DevOps

Fix Maven Failed to Execute Goal Compiler Plugin Errors

Read the maven-compiler-plugin failure to its real cause: a JRE instead of a JDK, a release the JDK lacks, annotation processing or a real compile error.

7 min read
Summarize in AI
Flat illustration of a dependency tree and build phases, with the Apache Maven, Docker, OpenJDK and Jenkins logos.

Every compile failure in Maven arrives under the same heading:

Text
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile) on project shop: Compilation failure

and then the useful part. The plugin's goal failed; the reason is what follows. This post lists the reasons in the order you are likely to meet them. For the settings that decide the Java version, see invalid target release, and for the build phases, Maven lifecycle.

A real compile error

Text
[ERROR] /home/dev/shop/src/main/java/dev/javahacks/Order.java:[14,23] cannot find symbol
[ERROR]   symbol:   class Money
[ERROR]   location: class dev.javahacks.Order

A normal Java compile error with a file, a line and a column. Fix the code. The two common reasons for a symbol that exists in your IDE and not in Maven: a missing dependency that the IDE got from another module, or a source folder that Maven does not use (Maven compiles src/main/java).

No compiler: a JRE, not a JDK

Text
[ERROR] No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK?

Maven runs on the Java in JAVA_HOME. A JRE has no javac. Point to a JDK and check with ./mvnw -v, which prints the Java home it uses. Details are in the JAVA_HOME error.

The release is not supported

Text
[ERROR] release version 25 not supported

The POM asks for Java 25 and Maven is running on an older JDK. Run Maven on a JDK at least as new as the release, or lower maven.compiler.release. A Maven toolchain pins the compiler JDK independently of JAVA_HOME.

Annotation processors stopped running

Lombok, MapStruct, Dagger, Hibernate's metamodel generator and Micronaut all rely on annotation processing. Starting with JDK 23, the compiler no longer runs processors that are only on the classpath, unless you enable it or name them. The symptom is a compile error about missing generated classes or methods (cannot find symbol: method builder()). Declare the processors explicitly:

pom.xmlXML
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <configuration>
        <annotationProcessorPaths>
            <path>
                <groupId>org.projectlombok</groupId>
                <artifactId>lombok</artifactId>
                <version>${lombok.version}</version>
            </path>
        </annotationProcessorPaths>
    </configuration>
</plugin>

annotationProcessorPaths is the supported way. Setting -proc:full in compilerArgs restores the old behavior but prints a warning that it will not stay the default. The Micronaut equivalent is in the no-bean error.

Out of memory or a crash in the compiler

java.lang.OutOfMemoryError inside the compiler happens for huge generated sources. Give Maven more memory with MAVEN_OPTS=-Xmx2g, or fork the compiler (<fork>true</fork> and <meminitial>/<maxmem>). An old compiler plugin with a new JDK can fail with an exception from the compiler API; upgrade maven-compiler-plugin to a current 3.x version.

Read more output

Shell
./mvnw -e -X compile 2>&1 | grep -A5 "javac"

-X prints debug information, including the exact command line given to the compiler. -e prints the stack trace of the failure. Look for the options such as --release, -proc and the classpath.

Reproduce the three messages you will see most

The line Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:... on project X is a wrapper, like the bean creation error in Spring. What follows it is the cause, and in practice there are three. These runs use Maven 3.9.11 with the compiler plugin 3.13.0.

The first is a real compile error in your code. A two-line class with a type mismatch and a missing method produces this:

Text
[ERROR] COMPILATION ERROR :
[ERROR] /proj/src/main/java/dev/javahacks/App.java:[5,23] incompatible types: int cannot be converted to java.lang.String
[ERROR] /proj/src/main/java/dev/javahacks/App.java:[6,32] cannot find symbol
  symbol:   method size()
  location: variable name of type java.lang.String
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile) on project demo: Compilation failure

The brackets [5,23] are line 5, column 23. Fix the code, not the build. The long trailing text about -e and -X is boilerplate that nobody needs.

The second appears when the release is newer than the JDK that runs Maven. Setting <maven.compiler.release>99</maven.compiler.release> on a JDK 17 gives:

Text
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile) on project demo: Fatal error compiling: error: release version 99 not supported

The same message appears with a realistic value, such as 25 on a machine whose mvn -v reports Java 17. The Java version that Maven runs on is shown in the second line of mvn -v, and it is the one that counts, whatever java -version printed in another terminal.

The third occurs when Maven runs on a JRE, which has no compiler:

Text
[ERROR] No compiler is provided in this environment. Perhaps you are running on a JRE rather than a JDK?

It appeared when the same project ran in the eclipse-temurin:25-jre image. Container images tagged jre are for running applications, and a build needs the jdk tag or a Maven image. CI runners often have both installed, and JAVA_HOME pointing at the wrong one produces this message.

A checklist in the order that finds it fastest

Run four commands and compare them. They separate the three causes in under a minute.

Shell
mvn -v                                      # the JDK Maven runs on, and its vendor
echo "$JAVA_HOME"; which javac              # is it a JDK, and is it the one you expect
mvn -q help:evaluate -Dexpression=maven.compiler.release -DforceStdout
mvn -B compile 2>&1 | grep -B2 -A6 'COMPILATION ERROR'

If javac does not exist under JAVA_HOME, it is a JRE. If the release number is higher than the major version in mvn -v, the JDK is too old. If the last command prints a compilation error, the code is the problem. A pipeline that passes locally and fails in CI nearly always differs in the first two lines, so print them at the start of the build log.

Pin the toolchain so the answer is the same everywhere

The structural fix is to stop depending on whichever JDK happens to run Maven. Maven's toolchains plugin selects a JDK by version for the compile step, and the release flag makes the compiler target that version regardless of the running JDK.

pom.xmlXML
<properties>
  <maven.compiler.release>25</maven.compiler.release>
</properties>

<build>
  <plugins>
    <plugin>
      <artifactId>maven-toolchains-plugin</artifactId>
      <version>3.2.0</version>
      <executions><execution><goals><goal>toolchain</goal></goals></execution></executions>
      <configuration><toolchains><jdk><version>25</version></jdk></toolchains></configuration>
    </plugin>
  </plugins>
</build>
~/.m2/toolchains.xmlXML
<toolchains>
  <toolchain>
    <type>jdk</type>
    <provides><version>25</version></provides>
    <configuration><jdkHome>/opt/jdk-25</jdkHome></configuration>
  </toolchain>
</toolchains>

With that in place a build on a developer laptop with JDK 17 Maven still compiles with JDK 25, and a CI image only needs the toolchain file. The Maven wrapper plus a version-pinned image removes most of the remaining differences.

When the compiler runs out of memory

The messages OutOfMemoryError: Java heap space or GC overhead limit exceeded in this step mean the compiler needs more heap, typical for large projects with annotation processors. Raise it through .mvn/jvm.config for Maven itself or through the plugin's fork and maxmem settings; a single line -Xmx2g in .mvn/jvm.config is the shortest fix and travels with the repository.

Make the failing step reproducible in one command

When the build fails only on a colleague's machine or in CI, a reproducible command saves hours. Capture the environment with a script that prints what matters, and attach its output to the report.

Shell
{ mvn -v; echo "JAVA_HOME=$JAVA_HOME"; mvn -q help:effective-settings | head -20; mvn -B -e compile -DskipTests 2>&1 | tail -40; } > build-diagnosis.txt

The file shows the Maven and Java versions, the settings in force (a mirror or proxy that blocks a plugin download is a frequent cause of a plugin failing to execute), and the end of the failing build with the stack trace. Compare the file from the working machine with the one from the failing machine, line by line. Differences in the Java vendor, the Maven version or the active mirror explain most of the disagreements, and the fix is to pin them in the wrapper, the toolchain and the CI image.

Where this does not apply

A failure in the test compile is maven-compiler-plugin:testCompile, with the same causes and one more: test dependencies missing from scope test, as in dependency scopes. The compiler plugin documentation and the [javac reference](https://docs.oracle.com/en/java/javase/25/docs/specs/man/javac.html) list the options.

Also inJava Core
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.