How to Force Maven to Update a Corrupted Local Repository

1. Overview

In this tutorial, we will learn how to force update a corrupted local Maven repository using a simple example that shows why the repository can become corrupted and how to fix it.

2. Prerequisites

To follow the commands you need a Spring Initializr project and have JDK and Maven installed.

3. Maven repository structure

Maven stores all project dependencies in the .m2 folder. For example, the repository structure looks like the image below.

As shown, Maven downloads all dependencies into the repository folder, so having the required artifacts in the local repository is necessary for runtime access.

4. Downloading dependencies

Maven works based on the pom.xml file. When Maven processes this file it downloads dependencies from the central Maven repository into the local repository; if a dependency already exists locally, Maven will not download it again.

Running the following commands triggers the download:

mvn package
mvn install

Both commands internally execute: mvn dependency:resolve Therefore you can resolve dependencies alone by running the dependency:resolve goal without using package or install.

5. Corrupted Dependencies

Network failures during download can corrupt dependencies. Maven reports this with a message such as: Could not resolve dependencies for project ... We will now see how to fix this issue.

6. Automatically Fixing the Corrupted Dependencies

When Maven reports a build failure it often shows the corrupted artifact: Could not transfer artifact [artifact-name-here] ... To resolve it you can use automatic or manual methods. Run repository updates in debug mode, adding the -U and -X options to see detailed information.

6.1 Force update all SNAPSHOT dependencies

Maven does not re‑download existing dependencies. To force an update of all corrupted SNAPSHOT dependencies, add the -U/--update-snapshots option:

mvn package -U
mvn install -U

Note that if Maven has already downloaded a SNAPSHOT with the same checksum, the option will not re‑download it.

This also packages or installs the project. Next we will see how to update the repository without including the current project.

6.2 Dependency resolution goal

You can tell Maven to resolve dependencies and update snapshots without using any package or install command by invoking the dependency:resolve goal with -U:

mvn dependency:resolve -U

6.3 Clean local repository goal

Since -U only re‑downloads corrupted SNAPSHOTs, a deeper clean may be required for locally corrupted artifacts. Use: mvn dependency:purge-local-repository The dependency:purge-local-repository goal cleans (deletes and optionally re‑resolves) artifacts in the local Maven repository; by default it re‑resolves them.

6.4 Clean local repository options

You can configure the clean operation to target specific groups by setting the resolutionFuzziness option for groupId and using the include option to match an exact group ID:

mvn dependency:purge-local-repository -Dinclude:org.slf4j -DresolutionFuzziness=groupId -Dverbose

The resolutionFuzziness option can take values version, artifactId, groupId, or file. The example above searches and cleans all artifacts in the org.slf4j group and enables verbose logging.

If matching files are found, the log shows:

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

To specify which artifacts to delete or refresh you can use include / exclude options:

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

7. Manual deletion of repository

Although -U and purge-local-repository can solve corrupted dependencies without refreshing everything, manually deleting the .m2 local repository forces Maven to re‑download all dependencies.

This is useful when old, possibly corrupted dependencies exist; a simple repackage or reinstall will then work. You can also use the dependency:resolve goal to resolve only your project's dependencies.

8. Conclusion

We discussed Maven options and goals that can force an update of a local repository, including -U, dependency:resolve, and purge-local-repository.

The examples are simple Maven commands that can be used in any project with a correctly configured pom.xml.