maven trouble-shooting checklist

In theory, in order to use maven to build a project, all you need to do is to download maven, then update ~/.bashrc to have maven bin in $PATH.

export PATH=/Users/youruser/Downloads/apache-maven-3.2.5/bin/:$PATH

However, in reality, sometimes your maven gets stuck when downloading dependencies. Don't blame yourself for fat fingers, for big projects, the maven build process different every single time! First of all, your dependency could have snapshot versions, which might get updated on the repo 5 minutes ago, so when maven downloaded the latest one, trouble is introduced. Even though your direct dependency have no snapshot version. Your indirect dependency could have snapshot version dependency, downloading them also brings new jars which brings trouble into your build process. Besides, your OS/network admin could applied rules on your account, so that some of your remote repos can no longer be reached. Your build will still go on because your cached jar in local repo, however the cached version is now differ from the latest version, so your build process will differ from your coworkers' build process. Even though nothing happens in the environment, your download could be erroneous during file transfer due to network package loss, memory buffer, stale file stub etc.

Here are a trouble-shooting checklist.

1. find which maven is used.

which mvn

This command also tells you the maven home location.

There are two locations where a settings.xml file may live:
The Maven install: ${maven.home}/conf/settings.xml
A user’s install: ~/.m2/settings.xml
The user's install takes precedence than the other.

check both settings.xml file to make sure what properties are override. Without override, you default maven repo should locate inside ~/.m2/repository

2.  find if the complained jar file is in your local and remote repo or not.
The maven build will check local cache first, then go to download the remote repo for snapshot versions and won't download the release versions.
If the jar file is in the local repository ~/.m2/repository. It could be corrupted during download. You can use
mvn clean -U package
to force maven to re-download the existing local repository files from remote repository.
To achieve the same goal, you can also delete that dependency folder, or even the entire ~/.m2/repository folder, so that maven can not find the jar in local cache and have to trip to the remote repository to re-download everything.

Notice often times, the maven is complain about a jar and its depended jar file chains -- check each one of them, not just the first one in the complained list!

If you are helping others to trouble shoot build issue and the complained jar files are in your local repo but not in the remote repo. Chances are it just builds for you but won't build for others. Because someone has deleted the needed jar files in the remote repository, leaving a bug in the unaware victim code base.

3. restart you computer if possible. It will fix weird issues related to memory and network policy etc. For example network policy changes when you work from home with vpn then work in office.

4. check eclipse maven settings.

in eclipse -> preferences -> maven -> user settings, make sure you didn't override any default settings, so that you are using the default local repository. If you don't want to rely on default, literally specify the default location so that you are sure.

right click the project, then "maven", then "update project..", you can check the force update check box to have eclipse do the equivalent of
mvn clean -U package

5. restart eclipse, eclipse could run into weird issue internally.

6. ask if other people has the same build issue, then ask them to send you the ~/.bashrc, ~/.bash_profile, ~/.m2/settings.xml, and the /path-to-maven-home/conf/settings.xml. Also ask for the result of ls -lrt ~/.m2/repository/path/to/complained/jar

7. if you are using git or svn, find out who added the dependency that causes the trouble, have a conversation about it.