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.
1. Confirm this is your error
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.org2. Check the cause
mvn -X -DskipTests package
mvn -q help:effective-settings
nslookup <host>
ping <host>3. Apply the safe fix
# 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-settings4. Verify it works
nslookup <host>
mvn -DskipTests packageDon't use unsafe shortcuts
- 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;