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.
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:
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:
The purpose of the dependency:purge-local-repository is to purge (delete and optionally re-resolve) artifacts from the local Maven repository. By default, artifacts 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” for the resolutionFuzziness option, and the exact group ID to search for using the include option:
mvn dependency:purge-local-repository -Dinclude:org.slf4j -DresolutionFuzziness=groupId -Dverbose
The resolutionFuzziness option can have the values: version, artifactId, groupId, file.
The example above will search for and purge all artifacts in the org.slf4j group. We've also set the verbose option so we can see detailed logs of the artifacts deleted.
If any files that match the condition are found, the log will display a text like:
Deleting 2 transitive dependencies for project [...] with artifact groupId resolution fuzziness [INFO] Purging artifact: org.slf4j:jul-to-slf4j:jar:1.7.31 Purging artifact: org.slf4j:slf4j-api:jar:1.7.31
Note that to specify the artifacts included or excluded for deletion or refresh, we can use the options include/exclude:
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.
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.