Error Knowledge Base Maven UNKNOWN_HOST_EXCEPTION

UnknownHostException while downloading dependencies

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

Where the Request Failed

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

Maven is telling you the request failed before it got a clean response back. Treat the connection path and the failing environment as the first suspects, not the package or image name.

Restore connectivity to the repository

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.

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.

Why It Happens

Usually this comes down to 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, or the repository URL hostname is wrong (typo) or the host is down.

Prove the Failing Environment Can Reach It

Re-run the Maven goal and confirm artifact downloads proceed without UnknownHostException, and confirm Maven can download at least one new artifact into ~/.m2/repository/.

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.

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

Prevent Repeat Connectivity Failures

To prevent this, standardize on a single internal mirror/repository manager endpoint for CI and developer machines, document required proxy/VPN settings for build environments, and prefer caching proxies to reduce reliance on external DNS/connectivity during builds.

Docs and source code

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;

Need help or found a mistake? Contact RepoFlow support for questions.

Join our mailing list