Fix it fast
Most likely: The machine running Maven cannot resolve the repository hostname through DNS, or it should be using a proxy/internal mirror but is trying to reach the wrong host directly.
Confirm this is your error
Match the output and confirm you are troubleshooting the same failure.
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.orgCheck the cause
Run focused checks to identify what is failing in this environment.
mvn -X -DskipTests package
mvn -q help:effective-settings
nslookup <host>
ping <host>Apply the safe fix
Use the smallest safe change that addresses the confirmed cause.
# Fix the repository URL, VPN, DNS, proxy, or mirror configuration, then retry.
mvn -U -DskipTests package
# If your network requires an internal mirror, configure the mirror in settings.xml and retry.
mvn -q help:effective-settingsVerify it works
Repeat the relevant checks and confirm the original error is gone.
nslookup <host>
mvn -DskipTests packageAvoid unsafe shortcuts
Keep security and data protections in place while troubleshooting.
- Do not change dependency coordinates when the hostname itself cannot resolve.
- Do not assume Maven Central is down before checking local DNS, VPN, proxy, and mirror settings.
- Do not hard-code temporary IP addresses for repository hosts, fix DNS or use the approved mirror.
Where the Request Failed
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.
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;