UnknownHostException while downloading dependencies

What This Error Means

The machine running Maven could not resolve the repository hostname via DNS, so Maven cannot download artifacts or metadata.

How to Fix It

Confirm the repository URL Maven is trying to use (use mvn -X if needed) and correct any typos.

If your network requires a proxy, configure it in ~/.m2/settings.xml under <proxies> and retry.

If external access is blocked, route builds through an internal repository manager mirror and update settings.xml mirror configuration.

Retry the build on a known-good network to rule out local DNS/VPN issues.

Why It Happens

DNS is misconfigured or temporarily unavailable on the machine running Maven.

A corporate network/VPN/firewall blocks DNS or blocks direct access to external repositories.

Proxy settings are required but not configured in ~/.m2/settings.xml.

The repository URL hostname is wrong (typo) or the host is down.

How to Verify

Re-run the Maven goal and confirm artifact downloads proceed without UnknownHostException.

Confirm Maven can download at least one new artifact into ~/.m2/repository/.

Manual DNS and proxy checks

Copy the hostname from the error output and confirm DNS resolution from the same machine/network.

Print effective settings and check whether a proxy is required:mvn -q help:effective-settings

If your organization requires a mirror/repository manager, confirm the build is pointing at that internal hostname instead of a blocked external one.

Examples

java.net.UnknownHostException: repo.maven.apache.org
[ERROR] Could not transfer artifact org.example:lib:pom:1.2.3 from/to central (https://repo.maven.apache.org/maven2): transfer failed: java.net.UnknownHostException: repo.maven.apache.org

How Maven reaches remote repositories

Maven downloads artifacts over HTTP(S) using the JVM networking stack.

Before Maven can connect, the hostname in the repository URL must resolve to an IP address via DNS.

If DNS fails (or is blocked), Maven cannot reach the repository and dependency resolution fails.

Prevention Tips

Standardize on a single internal mirror/repository manager endpoint for CI and developer machines.

Document required proxy/VPN settings for build environments.

Prefer caching proxies to reduce reliance on external DNS/connectivity during builds.

Where This Can Be Triggered

github.com/apache/maven/blob/maven-3.9.6/maven-core/src/main/java/org/apache/maven/project/DefaultProjectDependenciesResolver.java

DNS failures (UnknownHostException) bubble up as a transfer failure message from the underlying resolver/wagon layer and are included in Maven's dependency resolution exception (e.getMessage()). - GitHub

String msg = "Could not resolve dependencies for project " + project.getId() + ": " + e.getMessage();
DependencyResolutionException dex = new DependencyResolutionException(msg, e);
dex.setResult(e.getResult());
throw dex;