See how maven works inside – remote debugging plugins

England Who uses maven as I do for a long time, knows that sometimes things does not go as expected. So it’s necessary to look at the ultimate documentation: the source code! In this post I’ll show how to debug a maven plugin using Eclipse’s remote debugger. I’ve chosen for this example the maven-clean-plugin.

Ok, let’s start. First create a simple sample project:

    mvn archetype:create -DgroupId=com.wordpress -DartifactId=maven-debug

In the folder maven-debug, edit the pom.xml and add the dependency of the plugin. This will serve as an “anchor” to bring all the sources needed to debug.


Note the scope “provided”, meaning that the dependency will be given to the project by someone and it should not make to the final package. It shouldn’t matter, anyway, since this is a dependency that will be removed later, it’s just for debug purposes.

It’s important to know what version of the plugin your project is using. When in doubt, run “mvn -X clean” and note lines like:

  [DEBUG] Retrieving parent-POM: org.apache.maven.plugins:maven-plugins::3 for project: 
           null:maven-clean-plugin:maven-plugin:2.1.1 from the repository.

Now generate the project in eclipse:

   mvn -Declipse.downloadSources=true eclipse:eclipse

Open eclipse, go to File -> Import -> Existing Projects into Workspace and select the root directory of the project. After that go to menu
“Run –> Open debug dialog” and under “Remote java application” create a new profile to debug our project:

Using the eclipse search facilities, search for a class which name ends with “Mojo” (Maven Old Java Object) and place a breakpoint in the “execute” method. In the case of the clean plugin, this class is called CleanMojo

To debug, first enable debug on maven in the command line (linux shown here)

MAVEN_OPTS="-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000"; 

and then do a “mvn clean”; the process will halt. Start the debugger in eclipse, it will hit the breakpoint.


Congratulations! Now you can know exactly what’s going on!


11 comments on “See how maven works inside – remote debugging plugins

  1. […] Even recent posts still promote the -Djava.compiler=NONE  antipattern, as in See how maven works inside – remote debugging plugins. […]

  2. netsuke says:

    Indeed. Maven launch script ( includes the – Djava.compiler=NONE as the MAVEN_OPTS variable example. Not that removing this will make a perceptable difference on locally debugging a plugin, but can make a huge difference on debugging large systems…Anyway, I removed it from the post 😉

  3. Matteo says:

    I follow the step illustrated but when I run mvn war:war (because war is the plungin I need ti debug) it goes until the end of the process and I don’t kwon how and when attach the remote debuging!
    After I run the mvn command from prompt with the MAVEN_OPTS for remote debbuging on the project with the dependency to the plugin with the scope provided, should maven command wait untill I run the remote debug session?

    • asdac says:

      You can use the mvnDebug command. Basically it starts up, waits for a debugger, this gives you a chance to attach the remote debugger. Once attached mvnDebug continues with whatever tasks you told it to do.

  4. Fabrice says:

    Great ! Exactly what I need ! I did not know it was possible.

  5. Kiran says:

    remote debugging is the one way for maven debug,There are many ways to debug any maven projects. Documented 3 ways to debug maven projects #
    3 ways to debug maven builds

    • jumar says:

      None of aforementioned “3 ways to debug maven builds” actually does the same as described in this post. The last way is a true debugging, but applies only to tests.

  6. dipV says:

    I followed steps mentioned above but unfortunately its not working for me. I am newbie to maven. I am using maven3 on Windows.

    When I execute mvn3 clean, it does not halt at breakpoint.
    And when I launch eclipse remote debug config, it gives error as “Failed to connect to remote VM. Connection refused.Connection refused: connect”.

    Can you point me where its going wrong?

  7. Søren says:

    For Java7 (OpenJDK) i found that MAVEN_OPTS should be
    “-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000” (using -agentlib instead of -Xdebug -Xnoagent…)
    Thank you for a great post.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s