Maven build cache extension not restoring: the causes

You set up the Apache Maven Build Cache Extension against a self-hosted cache and the second build still compiles everything. Each cause below was reproduced for real, with Maven 3.10.0, extension 1.2.3 and a 0.2.1 server with a password. Find your symptom in the logs, then the fix.

First, what a healthy build looks like

The first build stores its result, and it looks alarming because a miss is logged as an error:

[INFO] Attempting to restore project demo:demo from build cache
[ERROR] Error downloading cache item: https://cache.example.com//v1.1/demo/demo/ebb9bceba2f7a6bc/buildinfo.xml
[INFO] Saved to remote cache https://cache.example.com//v1.1/demo/demo/ebb9bceba2f7a6bc/demo.jar
[INFO] Saved to remote cache https://cache.example.com//v1.1/demo/demo/ebb9bceba2f7a6bc/buildinfo.xml
[INFO] BUILD SUCCESS

That [ERROR] line is only the server saying it does not have the entry yet. What matters is the Saved to remote cache lines after it. After deleting target and the extension's local cache folder, the second build:

[INFO] Attempting to restore project demo:demo from build cache
[INFO] Found cached build, restoring demo:demo from cache by checksum ebb9bceba2f7a6bc
[INFO] BUILD SUCCESS

You must delete the local folder to prove the remote works, because the extension keeps its own local cache and will use it first.

Symptom 1: Maven stops with "Unrecognised tag: 'remote'"

Cannot initialize cache because xml config is not valid or not available
Unable to parse cache xml element: Unrecognised tag: 'remote' ...

Cause: the remote element is outside configuration. Fix: move it inside, as in the working file below. Nothing built, and the server saw nothing.

Symptom 2: the build succeeds, but the server stays empty

There are no Saved to remote cache lines, the second build says "Remote cache is incomplete or missing", and the server's status page shows store_entries: 0.

Cause: without saveToRemote="true" the extension reads from the server and never uploads. Fix: add it on the machines that should upload, usually CI.

Symptom 3: "HTTP Status: 401" in the log, and still no uploads

org.eclipse.aether.spi.connector.transport.http.HttpTransporterException: HTTP Status: 401

The build still ends in BUILD SUCCESS, the server stays empty, and the lines Saved to remote cache are missing. I got exactly this from two different mistakes:

• the id of the <server> in settings.xml did not match the id on the remote element, and
• the ids matched but the password was wrong.

Fix: make the two ids identical and check the password. Maven 3.10 may also print a warning about the credentials being used for an address without a matching repository entry. In my working setup the build behaved the same either way.

The working configuration

<?xml version="1.0" encoding="UTF-8"?>
<cache xmlns="http://maven.apache.org/BUILD-CACHE-CONFIG/1.2.0"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://maven.apache.org/BUILD-CACHE-CONFIG/1.2.0 https://maven.apache.org/xsd/build-cache-config-1.2.0.xsd">
  <configuration>
    <enabled>true</enabled>
    <remote enabled="true" saveToRemote="true" id="fosterstack-cache">
      <url>https://cache.example.com/</url>
    </remote>
  </configuration>
</cache>

With a password on the server, ~/.m2/settings.xml needs a matching <server> entry with <id>fosterstack-cache</id>. The full walk-through is in Maven build cache extension: remote server setup.

Check the server's side

The status page counts what arrived. After the healthy first build it showed store_entries: 3, and after the restoring build cache_hits: 2. If those stay at zero while your builds run, the problem is between Maven and the server, not in the project. See the HTTP status codes.

I did not test other Maven versions, or extension 1.2.0.