Skip to main content

How to upgrade a Maven package to a new version

· 3 min read

In theory, upgrading to a new version of a package, should be as simple as upgrading the pom.xml with the new version.

In practice, that often is not sufficient. This note covers the workarounds.

[!tldr] You may need to clear the local Maven package cache.

mvn dependency:purge-local-repository -DactTransitively=false -DreResolve=false

Motivating example​

I've ran into this issue before. This is just the example that prompted to write a note about it.

A few weeks ago, I upgraded the version of Spring Boot previously so I could implement @ControllerAdvice in order to include the Bean validation errors in the API response. That turned out to break the Swagger UI, though I didn't notice it until a week or so later, when I needed to use Swagger. This was the exception:

...
java.lang.NoSuchMethodError: 'void org.springframework.web.method.ControllerAdviceBean.<init>(java.lang.Object)'

The Swagger code was trying to call a method that no longer exists on the base class of the ControllerAdvice annotation.

I found the compatibility matrix and I just need to update springdoc-openapi-starter-webmvc-ui to 3.8. I tried this at the time, and it didn't work, for the reasons mentioned below, so I set it aside again, until now.

Upgrade process​

Determine target versions​

In my case, I needed to upgrade a specific version of a specific package, but if you want to be a bit more proactive, Maven supplies a command for this

mvn versions:display-dependency-updates

That command will show you all packages in your pom.xml which are not on the latest version, along with what the latest version number is.

If you don't want the latest version, you can search MVN Repository.

Update the pom.xml​

Once you know the version you want, you have to update the pom.xml. As near as I can tell, there is no mvn command for this, so you need to update it manually

diff --git a/pom.xml b/pom.xml
index 9e58490..a3c3e63 100644
--- a/pom.xml
+++ b/pom.xml
@@ -75,7 +75,7 @@
         <dependency>
             <groupId>org.springdoc</groupId>
             <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
-            <version>2.2.0</version>
+            <version>2.8.11</version>
         </dependency>

Clear cache and rebuild​

Maven caches downloaded packages in ~/.m2/repository. Purging this folder sometimes fixes the problem.

mvn dependency:purge-local-repository -DactTransitively=false -DreResolve=false

The extra flags are to keep it from automatically redownloading everything, and just fixing the project.

Rebuild with mvn clean compile.

Hotswapping doesn't seem to pickup version changes, so if you have a running service, kill it and restart.

You should be using the updated version now.

Troubleshooting​

If you get the following error from maven:

This failure was cached in the local repository and resolution is not reattempted until the update interval of global-artifact-registry has elapsed or updates are forced

Then you may have tried to run mvn clean compile before the artifact was available. In that case, if you don't want to wait for the interval to expire, you can use the -U flag to force it.

mvn clean install -U

References​