How to Fix Maven Build Failed Errors

In this tutorial, you'll learn about How to Fix Maven Build Failed Errors. We cover key concepts, practical examples, and best practices.

The Problem

You run mvn clean install and get:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.8.1:compile (default-compile) on project my-app: Fatal error compiling: invalid target release: 17

Or BUILD FAILED with dependency resolution errors, test failures, or plugin configuration problems. Maven errors can come from multiple stages: compilation, testing, packaging, or dependency resolution. The error output is verbose, but the first [ERROR] line usually contains the actual cause — everything after is often cascading failures.

Quick Fix

1. Read the first error (not the last)

mvn clean install 2>&1 | grep -A 5 "ERROR"

Expected output:

[ERROR] /home/user/project/src/main/java/App.java:[10,20] cannot find symbol
[ERROR]   symbol:   method println(String)

Scroll up to find the first [ERROR] — later errors are often cascading failures from the first problem.

2. Fix compiler target version mismatch

<properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
</properties>

Match these to your installed JDK version. Check with java -version:

java -version
# Output: openjdk version "17.0.9" ...

3. Clear the local repository (fix corrupted downloads)

rm -rf ~/.m2/repository
mvn clean install

Corrupted .jar files in ~/.m2/repository cause Could not resolve dependency or zip file is empty errors. Deleting the entire repo forces Maven to re-download everything. For a targeted fix, delete only the problematic artifact directory.

4. Skip tests for a quick build

mvn clean install -DskipTests

Use this to check if test failures are the only problem. If the build succeeds without tests, run mvn test separately to inspect test failures.

5. Add missing dependencies

<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>33.0.0-jre</version>
</dependency>

Search for the error message cannot find symbol or package does not exist. Find the required dependency at https://search.maven.org and add it to your pom.xml.

6. Use verbose output for debugging

mvn clean install -X

The -X flag enables debug logging. It shows dependency resolution, plugin execution order, and classpath details. Pipe to less for easier reading: mvn clean install -X | less.

7. Check Java and Maven versions

java -version
mvn -version

Expected output:

Apache Maven 3.9.6
Java version: 17.0.9

Some plugins require specific Maven or Java versions. For example, maven-compiler-plugin:3.11.0 requires Java 17+.

8. Fix plugin version

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.11.0</version>
        </plugin>
    </plugins>
</build>

Explicit plugin versions prevent build reproducibility issues. Old plugin versions may not support your Java version.

Prevention

• Specify explicit plugin versions in pom.xml
• Pin dependency versions (avoid LATEST or RELEASE)
• Use mvn dependency:tree to understand the dependency graph
• Run mvn clean before mvn install in CI to avoid stale artifacts
• Keep Maven and Java versions consistent across the team using a .mvn/jvm.config or .sdkmanrc file
• Always read the first [ERROR] in the output — later errors are often consequences of the first failure