Force Repository Update with Maven

1. Overview

In this tutorial, we'll learn how to force-update a local Maven repository when it becomes corrupted. To accomplish this, we'll use a straightforward example to understand why a repository can become corrupted and how to fix it.

2. Prerequisites

To learn and run the commands in this tutorial, we need to use a Spring Initializr project and have a JDK and Maven installed.

3. Maven Repository Structure

Maven saves all the dependencies of projects in the .m2 folder. For example, in the following image, we can observe the structure of Maven repositories:

As we can see, Maven downloads all dependencies under the repository folder. Therefore, the download into our local repository is necessary to access all needed code at runtime.

4. Downloading Dependencies

We know that Maven works based on the pom.xml file configurations. When Maven executes this pom.xml file, the dependencies will be downloaded from a central Maven repository and put into your local Maven repository. If we already have the dependencies in our local repository, Maven will not download them.

The download happens when we execute the following commands:

mvn package
mvn install

Both of the above include executing the following command:

mvn dependency:resolve 

Therefore, we can solely resolve the dependencies without using a package or install by just running the dependency:resolve command.

5. Corrupted Dependencies

While downloading the dependencies, a network glitch can happen, resulting in corrupted dependencies. The interrupted dependency download is the leading cause of corruption. Maven will display a message accordingly:

Could not resolve dependencies for project ...

Let's see next how we can solve this issue.

6. Automatically Fixing the Corrupted Dependencies

Maven usually displays the corrupted dependency when it notifies that the build failed:

Could not transfer artifact [artifact-name-here] ...

To fix this, we can have automatic or manual approaches. Additionally, we should run any repository update in debug mode, adding the -X option after -U to have a better picture of what happens during the update.

6.1. Force Update All SNAPSHOT Dependencies

As we know already, Maven will not download existing dependencies again. Therefore, to force Maven to update all corrupted SNAPSHOT dependencies, we should add in our command the  -U/–update-snapshots option:

mvn package -U
mvn install -U

Still, we have to remember that the option does not re-download a SNAPSHOT dependency if Maven already downloaded it and if the checksum is the same.

This will also package or install our project next. Finally, we'll learn how to update the repository without including the current working project.

6.2. Dependency Resolve Goal

We can tell Maven to resolve our dependencies and update snapshots without any package or install command. For this purpose, we'll use the dependency:resolve goal, by including the -U option:

mvn dependency:resolve -U

6.3. Purge Local Repository Goal

We know that -U  just re-downloads the corrupted SNAPSHOT dependencies. As a result, in the case of corrupted local release dependencies, we might need deeper commands. For this purpose, we should use:

mvn dependency:purge-local-repository

The purpose of the dependency:purge-local-repository is to purge (delete and optionally re-resolve) artefacts from the local Maven repository. By default, artefacts will be re-resolved.

6.4. Purge Local Repository Options

The purge local repository can be configured to run for only a certain group of dependencies by specifying the groupId, using the resolutionFuzziness option:

mvn dependency:purge-local-repository -DresolutionFuzziness=com.yyy.projectA:projectA

To add details, we might want to use the options includes/excludes to include or exclude artefacts for deletion or refresh:

mvn dependency:purge-local-repository -Dinclude=com.yyy.projectA:projectB -Dexclude=com.yyy.projectA:projectC

7. Manually Deleting the Repository

Whereas the -U option and purge-local-repository might resolve the corrupted dependencies without refreshing all of them, the manual delete of the .m2 local repository will cause a forced re-download of all dependencies.

This can be useful when having old and maybe corrupted dependencies. Then a simple re-package or re-install should do the job. Moreover, we can use the dependency:resolve option to solve the dependencies of our project solely.

8. Conclusion

In this tutorial, we discussed the options and goals of Maven that forcibly updates our local repository.

The samples used are simple Maven commands that can be used on any project with a proper pom.xml configured.