Maven Wrapper "Could not download" distribution in CI

By Kaveh Alemi·Latchkey

The mvnw wrapper downloads the Maven distribution named in .mvn/wrapper/maven-wrapper.properties on first run. In CI that download failed: a transient network drop, a 404 from a bad distributionUrl, or a blocked mirror.

What this error means

The job fails at ./mvnw ... with "Error downloading", "Could not download maven-3.9.6-bin.zip", or an HTTP 404/timeout before any goal runs.

mvnw output

Downloading https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip
Error: Could not download apache-maven-3.9.6-bin.zip
java.io.IOException: Server returned HTTP response code: 404 for URL: ...

Common causes

A wrong or stale distributionUrl

The version or path in maven-wrapper.properties does not exist on the server, so the wrapper gets a 404.

Transient network failure or blocked host

A timeout, reset, or a firewall blocking the distribution host stops the one-time download.

How to fix it

Correct the distributionUrl

Point the wrapper at a real, reachable Maven distribution version.

maven-wrapper.properties

# .mvn/wrapper/maven-wrapper.properties
distributionUrl=https://repo.maven.apache.org/maven2/org/apache/maven/apache-maven/3.9.6/apache-maven-3.9.6-bin.zip

Cache the wrapper distribution between runs

Persist ~/.m2/wrapper so the distribution downloads once and survives a flaky network.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.m2/wrapper
    key: mvnw-${{ hashFiles('.mvn/wrapper/maven-wrapper.properties') }}

How to prevent it

Keep distributionUrl pointed at a published version.
Cache the wrapper distribution directory across jobs.
Mirror the distribution internally if the public host is blocked.

Frequently asked questions

What causes ""Could not download maven-...-bin.zip""?

The version or path in maven-wrapper.properties does not exist on the server, so the wrapper gets a 404.

How do I fix "Could not download maven-...-bin.zip"?