Skip to main content
blog title image

5 minute read - Java For Testers Maven

Maven Troubleshooting FAQs and Tips

Aug 22, 2013

We use Maven in the Java For Testers book.

Once you have Maven running it tends to work fine. You mainly experience problems when you initially install it, at the point when you know how to nothing with Maven.

TIP: Debug maven issues from the command line, not from the IDE

Use the command line to debug maven problems, that way it is just Maven and Java that you are working with.

This way you can see the error messages generated.

TIP: Read the error messages

If maven is complaining about corrupt jars then chances are something went wrong when it was downloading the dependencies, delete them and try again.

If your compile is complaining that it can’t find classes from libraries in your class path then maven didn’t download the dependencies, delete them and try again.

You might be able to run with the “-q” option to zoom in on errors, warnings and messages output by the plugins.

TIP: Read and work through “Maven in 5 minutes”

Before doing anything.

Read and work through “Maven in 5 minutes”

This is a good check if you have installed maven correctly and if maven can connect to the internet. Since it is all done from the command line, any problems you encounter will be related to maven.

TIP: Compile without running tests

mvn clean compile -DskipTests=true

This helps you focus on the maven dependency problems, and you won’t be distracted by any other error messages.

Tip: Download issues

Maven shows you the urls it tries to download, try them manually by entering the URL in your browser.

Check your proxy settings, in case Maven is blocked by your firewall.

If a url fails, and you aren’t blocked try and force a download again with:

mvn clean -DskipTests=true

TIP: Set proxy settings for maven

Sometimes you have to amend the Maven settings.xml file to add a proxy or various repositories.

I had to do that a couple of days ago when experimenting with a 3rd party library.

What I sometimes forget, is that there are two settings.xml files. Now I shouldn’t forget this, because it is quite clear on the Maven Apache site.

But I do.

The settings.xml file in

  • %M2_HOME%/conf/settings.xml is the global settings.
  • your .m2 user directory is your user-specific settings.
    • This file doesn’t exist until you create it, which might explain why I forget about it.

Duplicate settings in the user-specific file, override the settings in the global settings.

I was reminded of this because of the permission schemes in Windows 7 which wouldn’t let me save my global settings without upping my permissions to admin.

You can see the combined settings if you issue the command:

mvn help:effective-settings

Some useful references:

TIP: Read the maven FAQs

Read the maven “how to I get help” section

TIP: Read some other hints and tips

see - Algorithm for troubleshooting “Maven doesn’t work for me” problems

TIP: Force update of dependencies

mvn clean compile -U -DskipTests=true

TIP: Delete your local repository cache

from %UserProfile%/.m2/repository

delete whichever folders you want from the cache to force a download, then do a …

mvn clean compile -DskipTests=true

TIP: Force a purge of local repository

mvn dependency:purge-local-repository

TIP: Look at the effective pom and settings

mvn help:effective-pom

Shows you the full pom, with the fields, defaults, inheritence and paths.

mvn help:effective-settings

Shows the settings with full output

TIP: Use the dependency tree

A bit more advanced but…

mvn dependency:tree

Can show you all dependencies and versions, if you have ordering clashes then this might reveal them.

Getting Maven Settings to Persist on a Mac

  • remember to edit the bash profile to persist settings

The M2 and M2_HOME variables are really only required for older versions of Maven, but some tools might still need them.

I installed Java and Maven on my mac. The default Java install for mac worked fine and setup my JAVA_HOME etc., all fine.

I installed Maven and followed the instructions on my mac. (

Again fine…

Until I restarted my mac or created a new terminal.

Then I found the additional secret instructions, which I’d forgotten because I’ve been away from Unix for so long.

I needed to edit the bash profile.

As explained in this StackOverflow article “mvn-command-not-found-in-osx

I needed to:

vi ~/.bash_profile

Then add the lines

export M2_HOME=/usr/local/apache-maven/apache-maven-3.2.1
export M2=$M2_HOME/binexport PATH=$M2:$PATH

I skipped the JAVA_HOME because when I typed echo $JAVA_HOME in the terminal it had already been exported correctly. If you had to add the JAVA_HOME variable during your installation then you might need to add the export for that in your bash_profile as well.

Remember, with vi, to save the file, press ’esc’ and then type ‘:wq’

esc :wq

I then opened a new terminal, and typed mvn and all was well.

Final Notes

  • Run Maven from the command line
  • Read the error messages
  • Google for the error messages.
    • Other people will have faced the same problem.
  • Experiment with these tips

Do all of this, Before you ask for help. That way you will learn more about how maven works, and won’t be so dependent on other people.

The biggest thing I always encourage people to do when they encounter a problem? Try and solve the problem yourself. Don’t immediately run to someone for help.

When you try and solve the problem yourself, you learn a bit more about the tool. You learn how it works and hangs together. You force yourself to experiment and immediately overcome that ‘but if I touch it, it might break’ response.

I listed the main steps and actions I take in a pdf which I released to Slideshare and Google Docs.