settings.xml, mirrors and the repository location
A pom describes a project and travels with it. A settings file describes a machine: where the local repository is, whether the network may be used, which repository replaces which, and the credentials of a server. It is not in a repository and not in a jar; it belongs to the person or the CI runner that runs Maven. This image has a one-line one, and this article adds a second one to show what a mirror does to a build.
The settings file
Maven reads two settings files: the global one in $MAVEN_HOME/conf/settings.xml, which an installation sets for every user, and the user one at ~/.m2/settings.xml, which wins over it. This image has the second, and it is one line:
~/.m2/settings.xml
<settings><offline>true</offline></settings>
The file needs no XML declaration and no namespace, because Maven reads it with a parser that does not validate it. That also means a misspelled element is ignored without a word: a settings file is the one file of a Maven setup where a typo fails silently.
A settings file with a mirror
A file of the shape a company machine has, written next to the project and given to Maven with -s. It is offline as well, so that the runs below stay inside this image, and it sends every request for central to a Nexus whose host does not exist:
settings-mirror.xml
<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
<offline>true</offline>
<mirrors>
<mirror>
<id>nexus</id>
<name>Company Nexus</name>
<url>http://nexus.example.com/repository/maven-public/</url>
<mirrorOf>central</mirrorOf>
</mirror>
</mirrors>
</settings>
-s replaces the user settings file for one run; -gs does the same for the global one. A build that reads the file runs exactly as before while nothing has to be resolved from the network:
mvn -B -s settings-mirror.xml validate > validate.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" validate.log
status: 1
[INFO] Scanning for projects...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
[ERROR] The goal you specified requires a project to execute but there is no POM in this directory (<project>). Please verify you invoked Maven from the correct directory. -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/MissingProjectException
What a mirror does
A mirror is a repository that stands in for another one. mirrorOf decides which: central is the one repository every pom has, * is every repository, external:* is every repository that is not on this machine, and the negation *,!my-repo is all but one.
The effect is immediate and visible in the first line Maven prints for a resolution: the repository the build asks is now called nexus, with the URL of the mirror, and the offline rule applies to it. A goal whose plugin metadata has to be looked up in a group fails at once, because the metadata of that group was cached under the id central and the build now asks nexus:
mvn -B -s settings-mirror.xml org.apache.maven.plugins:maven-dependency-plugin:3.7.0:get -Dartifact=org.mockito:mockito-core:5.14.2 > get.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" get.log
status: 1
[INFO] Scanning for projects...
[INFO] Artifact org.apache.maven.plugins:maven-dependency-plugin:pom:3.7.0 is present in the local repository, but cached from a remote repository ID that is unavailable in current build context, verifying that is downloadable from [nexus (http://nexus.example.com/repository/maven-public/, default, releases)]
[WARNING] The POM for org.apache.maven.plugins:maven-dependency-plugin:jar:3.7.0 is missing, no dependency information available
[INFO] Artifact org.apache.maven.plugins:maven-dependency-plugin:jar:3.7.0 is present in the local repository, but cached from a remote repository ID that is unavailable in current build context, verifying that is downloadable from [nexus (http://nexus.example.com/repository/maven-public/, default, releases)]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------
[ERROR] Plugin org.apache.maven.plugins:maven-dependency-plugin:3.7.0 or one of its dependencies could not be resolved:
[ERROR] Cannot access nexus (http://nexus.example.com/repository/maven-public/) in offline mode and the artifact org.apache.maven.plugins:maven-dependency-plugin:jar:3.7.0 has not been downloaded from it before.
[ERROR] -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/PluginResolutionException
The repository id in the cache
Two lines of that log are the whole story of a local repository that seems to have an artifact and does not have it:
Artifact org.apache.maven.plugins:maven-dependency-plugin:jar:3.7.0 is present in the local repository, but cached from a remote repository ID that is unavailable in current build context, verifying that is downloadable from [nexus (...)] is the sentence to remember.
present in the local repository, but cached from a remote repository ID that is unavailable in current build context: every file in ~/.m2/repository is recorded in _remote.repositories with the id of the repository it came from, which is why the same artifact cannot be silently reused when a mirror changes the ids. The resolver re-checks the artifact against the new repository, the settings are offline, and the check fails.
Three ways out, all real: point the mirror at the same id the artifacts were cached from, turn offline off and let the mirror serve them, or delete the version folders and resolve again. The error names the repository id it wants (nexus) and the artifact, so the first of the three is usually the cheapest.
The other elements
Five more elements of the file are worth knowing by name:
- <localRepository> moves the local repository from ~/.m2/repository; the local repository article shows the same change from the command line.
- <servers> holds the credentials of the repositories that need them, matched by id: a username and a password, or a key file. Never in a pom, which is shared.
- <proxies> describes an HTTP proxy, with its nonProxyHosts exception list.
- <profiles> adds properties, repositories and plugin repositories for a machine; unlike a profile of a pom it cannot add a dependency of a project.
- <pluginGroups> adds a group id to the search a prefix such as compiler: does, which is how a company plugin gets a short name.
Maven 3.9 ships one mirror of its own even when the file is empty: maven-default-http-blocker, whose mirrorOf is external:http:* and whose URL is 0.0.0.0. It blocks every plain-HTTP repository, which is why an old pom with an http:// repository fails on 3.9 with a message about a blocked mirror and works on 3.8.
Where to go next
The wrapper and a fat jar shows the two pieces of a Maven setup that this image cannot run, each with the failure that proves it.
Article author: Arthur Isaev