Maven "Connection refused" / Transfer Failures to Repository in CI

Maven could not open a connection to the repository or mirror it was downloading from. This is usually a transient network blip, an overloaded mirror, or a proxy that was unreachable for a moment.

What this error means

Resolution fails with Could not transfer artifact ...: Connection refused or Connection timed out. Re-running the job often succeeds without any change - the hallmark of a transient network failure.

mvn output

[ERROR] Failed to execute goal ... Could not transfer artifact
org.apache.commons:commons-lang3:jar:3.14.0 from/to central
(https://repo.maven.apache.org/maven2): Connect to repo.maven.apache.org:443
failed: Connection timed out

Common causes

Transient network or mirror slowness

A brief connectivity drop or an overloaded mirror causes the connection to fail. Nothing is wrong with the POM - the next run usually works.

Proxy or DNS misconfiguration

If the runner sits behind a proxy that Maven does not know about, or DNS for the repo host fails, every transfer fails until the network config is fixed.

How to fix it

Retry with bounded backoff

Because the failure is transient, a short retry of the resolution step often succeeds. Configure the wagon to retry rather than failing on the first blip.

Terminal

mvn -B \
  -Dmaven.wagon.http.retryHandler.count=3 \
  -Dmaven.wagon.httpconnectionManager.ttlSeconds=120 \
  clean verify

Use a mirror and cache ~/.m2

Resolve through a stable internal mirror and cache the local repository so most artifacts are already present.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.m2/repository
    key: maven-${{ hashFiles('**/pom.xml') }}

Configure the proxy if one is required

Declare the proxy in settings.xml so all wagon transfers route through it.

~/.m2/settings.xml

<proxies>
  <proxy>
    <id>corp</id><active>true</active><protocol>https</protocol>
    <host>proxy.example.com</host><port>3128</port>
  </proxy>
</proxies>

How to prevent it

Resolve through a pull-through mirror (Nexus/Artifactory) to reduce dependence on public Central.
Cache ~/.m2/repository keyed on the POMs.
Set wagon retry counts so a single blip does not fail the build.