How can I manually validate maven:COULD_NOT_TRANSFER_ARTIFACT?

Copy the repository URL from the error output and test basic reachability (DNS + TCP + TLS). Check whether Maven is configured with a proxy: `mvn -q help:effective-settings` (look for ` `). Run once with full debug output to see the exact URLs and transports being used: `mvn -X -DskipTests package`. If the failure is intermittent, retry the same build on a stable network and compare results.

Could not transfer artifact ...: transfer failed

Q: How do I prevent maven:COULD_NOT_TRANSFER_ARTIFACT in CI?

Use a local repository manager proxy to reduce network dependency on upstream repositories. Keep proxy and mirror configuration consistent across developer and CI environments. Avoid mixing multiple repository URLs across projects; prefer one mirrored endpoint.

Where the Request Failed

Maven could not transfer the artifact from the repository, usually because of network failures, proxy issues, TLS problems, or bad credentials.

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

Start by proving the failing machine can reach the right host cleanly. Until DNS, routing, proxy, and trust look sane in that exact environment, retrying the install or pull is mostly noise.

Identify the exact repository host and URL Maven is trying to reach (copy it from the error line).

If you are behind a corporate proxy, configure it in ~/.m2/settings.xml under <proxies> and re-run the build.

If the error is TLS-related, fix certificate trust for the JDK running Maven (import the corporate/root CA), then retry.

Force Maven to retry metadata/artifacts once:mvn -U -DskipTests package

If your repository is self-hosted, check repository health (HTTP status, storage, TLS cert validity) and try again.

Re-run with debug logs if you still can't see the root cause:mvn -X -DskipTests package

Manual network and repository checks

Copy the repository URL from the error output and test basic reachability (DNS + TCP + TLS).

Check whether Maven is configured with a proxy:mvn -q help:effective-settings (look for <proxies>).

Run once with full debug output to see the exact URLs and transports being used:mvn -X -DskipTests package

If the failure is intermittent, retry the same build on a stable network and compare results.

Why It Happens

The repository host is down or temporarily unreachable. A firewall/VPN/proxy blocks Maven from reaching the repository (or performs TLS interception without a trusted CA). DNS resolution fails for the repository hostname. The connection is being reset or timing out (unstable network, packet loss, overloaded proxy). Maven is running in offline mode (-o) and cannot refresh missing artifacts.

Prove the Failing Environment Can Reach It

Re-run the original Maven goal and confirm artifacts/metadata are downloaded successfully, and confirm the artifact now exists in the local repository under ~/.m2/repository/.

How Maven downloads artifacts

Maven downloads artifacts (and metadata like maven-metadata.xml) over HTTP(S) from your configured repositories. Network errors, proxies, TLS inspection, DNS failures, or repository outages can cause transfers to fail even when coordinates are correct.

Examples

[ERROR] Could not transfer artifact org.example:lib:jar:1.2.3 from/to central (https://repo.maven.apache.org/maven2): transfer failed for https://repo.maven.apache.org/maven2/org/example/lib/1.2.3/lib-1.2.3.jar
[ERROR] Could not transfer metadata org.example:lib/maven-metadata.xml from/to internal (https://repo.example.com/maven): transfer failed for https://repo.example.com/maven/org/example/lib/maven-metadata.xml

Prevent Repeat Connectivity Failures

To prevent this, use a local repository manager proxy to reduce network dependency on upstream repositories, keep proxy and mirror configuration consistent across developer and CI environments, and avoid mixing multiple repository URLs across projects, prefer one mirrored endpoint.

Docs and source code

github.com/apache/maven/blob/maven-3.9.11/its/core-it-suite/src/test/java/org/apache/maven/it/MavenITmng7128BlockExternalHttpReactorTest.java

Maven's integration tests assert the exact "Could not transfer artifact ..." output when an HTTP repository is blocked (MNG-7128). - GitHub

verifier.verifyTextInLog( "[ERROR] Failed to execute goal on project http-repository-in-pom: "
        + "Could not resolve dependencies for project org.apache.maven.its.mng7128:http-repository-in-pom:jar:1.0: "
        + "Failed to collect dependencies at junit:junit:jar:1.3: "
        + "Failed to read artifact descriptor for junit:junit:jar:1.3: "
        + "Could not transfer artifact junit:junit:pom:1.3 from/to maven-default-http-blocker (http://0.0.0.0/): "
        + "Blocked mirror for repositories: [insecure-http-repo (http://repo.maven.apache.org/, default, releases+snapshots)]" );