3 ways to debug maven build: maven debug tutorials

Maven is an automated build project management tool that automates the build process by defining all the dependencies in pom.xml.

Developers often face challenges when building and running Maven projects, both during the development and release phases. This article delves into various methods for debugging issues with Maven builds. Additionally, you can explore more about maven commands in my other posts, such as this one.

Now, let’s explore different approaches to debugging Maven build issues.

  • command line using -x or --debug or -e.
  • mvn dependency tree
  • debugging with the Maven Surefire plugin

I am listing down the required steps for finding out the real issues.

Maven debug mode

When encountering issues with running Maven goals like compile or install, the displayed information messages may not always provide the exact cause of a failure. In such cases, consider running the maven command with options such as -X, -e, or --debug flags. These flags provide clearer messages, including the location of the error, plugin configuration details, and comprehensive class loading information.

This approach is particularly useful for Maven users to identify the root cause of an issue.\

mvn -X  prints debugging messages
mvn -e shows error messages
mvn -e shows error messages

Please note that the debugging information provided by these options pertains to Maven’s internal processes during the build of your project. This is distinct from debugging your project code, which involves different concepts. I plan to write another post later on Java project debugging tips.

Enabling these options will initiate Maven in debug mode, offering comprehensive information about the dependencies being loaded into your project and the goals that are currently running.

Dependencies issues in Maven

In real-time Maven project builds, we often encounter version issues with direct dependencies and indirect dependencies.

For instance, in your project, you might have a direct dependency on a module, let’s say log4j-1.2.12. Simultaneously, there could be an indirect dependency on the same log4j-1.2.12 arising from another module, such as spring 2.0.6, which itself is a dependency for your project. In such a scenario, your project ends up with two instances of the same module (log4j) but with different versions. This discrepancy leads to compatibility issues during class loading when the project is initiated on the web server.

To resolve this, you must include the required module in your pom.xml and exclude the redundant module by specifying the exclusion configuration.

To identify these issues, run the dependency tree for your project, with the following command.

mvn dependency:tree

This lists out all the dependencies for your project in Tree Explorer format. all these dependencies are downloaded to your local repository.

You can find out which version to keep and exclude as seen below if we want to exclude log4j from spring dependency, You can use the exclusions and exclusion tags in the dependency tag.


Debugging tests with maven surefire

We will use mvn test for running test cases of your maven project. As you know the Maven Surefire plugin is used to run the unit test of your project.

You have to provide the maven.surefire.debug property with maven test goal

mvn -Dmaven.surefire.debug test

This will run the tests in a separate process. This will be on port 5005. You can attach this process to Eclipse for remote debugging.

In the eclipse, you have to create and configure the maven debug options as follows.

hostname is localhost

`and port  is 5005`

One of the coolest features offered by Maven is Eclipse remote debugging. When initiating the execution of Maven test cases, you can strategically place breakpoints in your test classes to halt the debugger for debugging purposes. Once the Maven execution concludes, the Eclipse debugger automatically terminates the process.

Alternatively, to avoid running the debugger in fork mode, which involves executing tests in the same process, you can use

mvn -DforkMode never test