Maven "Connection reset" on Artifact Transfer - Fix Flaky Downloads

By Kaveh Alemi·Latchkey

The repository or an intermediary reset the TCP connection while Maven was downloading an artifact. This is a transient network event - the same fetch usually succeeds on the next attempt.

What this error means

Resolution fails partway through a download with Could not transfer artifact ...: Connection reset. A re-run often completes cleanly, which is the signature of a transient drop rather than a config problem.

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): Connection reset

Common causes

Transient TCP reset from the repo or proxy

An overloaded mirror, a proxy idle-timeout, or a brief network blip sends an RST mid-transfer. Nothing in the build is wrong.

Keep-alive/idle timeout on a slow large download

A large artifact downloaded over a slow link can exceed a proxy or LB idle timeout, which then resets the connection.

How to fix it

Enable wagon retries

Let the HTTP wagon retry the transfer so a single reset does not fail the build.

Terminal

mvn -B \
  -Dmaven.wagon.http.retryHandler.count=3 \
  -Dmaven.wagon.http.retryHandler.requestSentEnabled=true \
  clean verify

Cache ~/.m2 and resolve through a mirror

Most artifacts already present means fewer live downloads to drop. A stable mirror reduces resets further.

.github/workflows/ci.yml

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

How to prevent it

Set wagon retry counts so one reset does not fail the build.
Cache ~/.m2/repository keyed on the POMs.
Resolve through a pull-through mirror to cut live downloads.

Frequently asked questions

What causes ""Connection reset""?