skip to content

How do <mirrors> and the mirrorOf syntax work in settings.xml?

level: seniorimportance: must knowfreq 60%

answer

  1. mirror redirects repo requests to one URL
  2. mirrorOf matches by repo <id>
  3. = all, external:* = exclude local/file
  4. *,!internal exclusion pattern
  5. one mirror per repo (first match); auth binds to mirror id

basics

~10 s

A <mirror> redirects requests for one or more repositories to a different URL. The <mirrorOf> element says which repository IDs the mirror replaces. mirrorOf=* matches every repo; you can also use patterns and exclusions.

solid answer

~40 s

A `<mirror>` in settings.xml intercepts requests bound for declared repositories and reroutes them to the mirror's URL — typically a corporate repository manager (Nexus/Artifactory) that proxies Maven Central and hosts internal artifacts. The `<mirrorOf>` element selects which repositories this mirror covers, matched by their **`<id>`**. Values: a specific id; `*` (all); `external:*` (all except localhost/file repos); `external:http:*`; a comma list with exclusions like `*,!internal-repo`. Only ONE mirror serves a given repo — Maven picks the first matching mirror by file order. The mirror's own `<id>` is then what binds to a `<server>` for authentication, since the mirror URL is what's actually contacted. Common use: `<mirrorOf>*</mirrorOf>` to force every build through one company proxy for caching, governance, and to avoid hitting Central directly.

code

xml · 6 lines
xml
<mirror>
  <id>company-nexus</id>
  <url>https://nexus.example.com/repository/maven-public/</url>
  <!-- mirror everything except the internal snapshots repo -->
  <mirrorOf>*,!internal-snapshots</mirrorOf>
</mirror>

go deeper

for a junior

Knows a mirror redirects repo requests to another URL (e.g. company Nexus).

for a middle

Understands mirrorOf=* and that matching is by repo id.

for a senior

Uses external:*, exclusion patterns, knows one-mirror-per-repo + first-match, and mirror-id auth.

for a principal

Designs the org repository-manager topology: single chokepoint for caching/security/license policy, air-gap strategy, mirror governance.

## What a mirror does When Maven needs an artifact, it consults the repositories declared in the POM/super-POM (e.g. Maven Central). A `<mirror>` lets you **transparently redirect** those requests to a different URL without changing the POM. The classic use is routing all traffic through a corporate **repository manager** (Nexus/Artifactory) that caches Central, hosts internal releases, and enforces policy. ```xml <settings> <mirrors> <mirror> <id>company-nexus</id> <name>Internal proxy</name> <url>https://nexus.example.com/repository/maven-public/</url> <mirrorOf>*</mirrorOf> </mirror> </mirrors> </settings> ``` ## mirrorOf matching syntax `<mirrorOf>` matches repositories by their declared `<id>`: - `central` — mirror only the repo with id `central`. - `*` — mirror **every** repository. - `external:*` — every repo **except** those on localhost (`localhost`, `127.0.0.1`) or `file://` URLs. - `external:http:*` — external repos served over plain http. - `repo1,repo2` — a comma-separated list. - `*,!internal` — all repos **except** `internal` (the `!` excludes). This is the key pattern when you want one mirror for everything but still reach an internal repo directly. ## One mirror per repository A given target repository is served by exactly **one** mirror. If multiple mirrors match, Maven uses the **first** one in file order. So ordering and exclusions matter. ## Authentication of mirrors Because the mirror URL is the one actually contacted, credentials must be attached to the **mirror's** `<id>` via a `<server>` entry — not the original repository's id. A frequent bug: server id set to `central` while the mirror id is `company-nexus`, yielding 401s. ## Why teams use mirrors - **Caching/speed**: artifacts come from a nearby proxy. - **Reliability**: builds don't break when Central is slow/down. - **Governance/security**: a single chokepoint can block disallowed licenses or vulnerable versions and provide an audit trail. - **Air-gapped builds**: combined with `<offline>` or an internal-only mirror.

  • You want all traffic through Nexus except one internal repo reached directly. What mirrorOf value?
    <mirrorOf>*,!internal-repo-id</mirrorOf> — match all repos but exclude the internal one with the ! prefix.
  • Two mirrors both match repository 'central'. Which is used?
    Only one mirror serves a repo; Maven uses the first matching <mirror> in document order.
  • When mirroring an authenticated Nexus, which id must the <server> use?
    The mirror's <id>, because the mirror URL is what Maven actually contacts.

Like a corporate web proxy: every outbound request is funneled through one gateway that caches, filters, and logs, instead of each machine hitting the internet directly.

saying these in an interview costs you the question

  • Thinking mirrorOf matches by URL instead of repository <id>.
  • Believing multiple mirrors can each partially serve one repo (only one wins).
  • Attaching credentials to the original repo id rather than the mirror id.
  • Confusing a mirror (redirect) with a proxy (<proxies>, network HTTP proxy).

context

resolving links…