Maven Commands Cheat Sheet: mvn Examples and Common Errors

Before a commit, a developer runs mvn clean install -DskipTests out of habit and sees BUILD SUCCESS. The check the command was meant to provide never happened: the tests were skipped, yet a jar with untested code is now installed into ~/.m2/repository, and any project that depends on this SNAPSHOT version will pick it up on its next build. The right pre-commit command is mvn verify, and clean is not needed every time — only when target may still hold leftovers of deleted classes.

The mvn command runs Maven from the command line in the form mvn [options] [phases and goals]. A phase (compile, package, verify) runs the lifecycle up to and including itself, a plugin goal written as prefix:goal (dependency:tree) performs a single plugin action without any previous steps, and options (-U, -o, -pl, -D) change how Maven works. Below is a Maven cheat sheet of the mvn commands from the whole module, with links to the detailed lessons, plus a table of common build errors. The examples target Maven 3.9.x.

mvn Syntax: Phases, Goals and Options

A Maven command consists of options and a list of phases and goals, which run from left to right. A phase triggers every earlier phase of its lifecycle, while a goal runs only itself. A goal is written with the plugin prefix (dependency:tree) or with the full coordinates groupId:artifactId[:version]:goal.

By default Maven resolves short prefixes in the org.apache.maven.plugins and org.codehaus.mojo groups, which is why exec:java and versions:... work without being declared in pom.xml. When a build fails, mvn exits with a non-zero exit code — CI scripts rely on this. The difference between a phase and a goal, with the empty-jar example, is in the section Maven Goals vs Phases; the ways to invoke a plugin are in Plugins and Goals.

Build Commands: clean, package, verify, install

For everyday builds the compile, test, package and verify phases are enough: verify runs all tests and checks and leaves the artifact in target. install is needed only when another project on the same machine must see the artifact, and deploy publishes it to a remote repository.

A multi-module project does not need install to connect its modules: within one build the reactor hands each module the results of its siblings directly (Aggregation and the reactor).

Running and Skipping Tests: -DskipTests and -Dtest

To skip tests in Maven, use -DskipTests: the test code is compiled but not run. -Dmaven.test.skip=true does not compile the tests at all and is rarely needed. A single class or method is run with the Surefire parameter -Dtest, a single integration test with the Failsafe parameter -Dit.test.

Running the Application

Maven builds the application, but it is usually easier to run it with the plain java command. For a quick run straight from the sources there is the exec:java goal of exec-maven-plugin (MojoHaus, org.codehaus.mojo): it calls the main method inside the JVM of Maven itself, with the project classpath.

Dependencies and Version Updates

Dependency commands come from two plugins: maven-dependency-plugin (tree, analysis, download, local repository cleanup) and versions-maven-plugin from MojoHaus (finding newer versions of libraries and plugins). None of these goals changes pom.xml, except versions:set and the other versions goals that explicitly edit versions.

Diagnostics: the help Plugin

When a build behaves unexpectedly, first check what Maven actually received as input: the effective POM, the settings, the active profiles and the goal bindings. All of this is shown by maven-help-plugin, and none of its goals runs a build.

An example for a build script (the forceStdout parameter exists in maven-help-plugin 3.1.0 and newer):

VERSION=$(mvn help:evaluate -Dexpression=project.version -q -DforceStdout)
echo "$VERSION"
# Output: 1.0-SNAPSHOT

Multi-Module Projects

In a multi-module project, commands are run from the root, and a subset of modules is selected with reactor options: -pl picks the modules, -am adds the modules they depend on, and -amd adds the modules that depend on them. Without -am, sibling modules are taken from ~/.m2, that is, in their old version.

Creating a Project and the Maven Wrapper

A new project is created with the archetype:generate goal, and the Maven Wrapper pins the Maven version for the whole team: after mvn wrapper:wrapper the project is built with the ./mvnw script, which downloads the required Maven version by itself.

Useful mvn Options

Options can be written before or after the phases, in any order. The typical set for CI is -B (no interactive prompts and no colored output) and -ntp (no download progress lines): mvn -B -ntp clean verify. The full list is printed by mvn -h.

Options needed on every run of a project go into the .mvn/maven.config file in the project root (the safest form is one argument per line, for example -ntp and -Dstyle.color=always). JVM settings of Maven itself (memory, encoding) are set with the MAVEN_OPTS environment variable, for example MAVEN_OPTS="-Xmx2g", or in the .mvn/jvm.config file.

Common Maven Build Errors and How to Fix Them

Almost every Maven build error starts with a [ERROR] Failed to execute goal line or with a POM reading error before the build begins. The first line already contains the essentials: which plugin and goal failed, in which module, and why. More details come from a rerun with -e (exception stack trace) and -X (debug log).

An example (approximate form for Maven 3.9.x; the path and line number depend on the project):

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.13.0:compile (default-compile) on project shop-web: Compilation failure
[ERROR] /home/user/shop/shop-web/src/main/java/com/examclouds/web/App.java:[12,9] cannot find symbol
...
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.

How to read it: maven-compiler-plugin:3.13.0:compile is the plugin, its version and the goal; (default-compile) is the execution id: the default- prefix means the standard binding to a phase, default-cli means the goal was called from the command line, and any other name is an execution from your pom.xml; on project shop-web is the module; after the colon comes the cause. The following lines refine the cause, and in a multi-module build the end of the log suggests -rf :shop-web. The messages in the table below are shortened; the exact wording depends on the Maven and plugin versions.