Gradle wrapper "Downloading ... gradle-X-bin.zip failed" behind a proxy in CI

The Gradle wrapper downloads the distribution named in distributionUrl before any build runs. When CI sits behind a proxy or has restricted egress, that download to services.gradle.org fails and the wrapper aborts.

What this error means

The wrapper prints "Downloading https://services.gradle.org/distributions/gradle-8.7-bin.zip" then fails with a java.net.ConnectException, a timeout, or a TLS error before Gradle starts.

Gradle

Downloading https://services.gradle.org/distributions/gradle-8.7-bin.zip
Exception in thread "main" java.net.ConnectException: Connection timed out
	at java.base/sun.nio.ch.Net.pollConnect(Native Method)
	at org.gradle.wrapper.Download.downloadInternal(Download.java:...)

Common causes

Restricted egress or a required proxy

The runner cannot reach services.gradle.org directly; a proxy is required and not configured for the wrapper JVM.

A slow or flaky download of the distribution zip

A large distribution over a congested link times out before completing.

How to fix it

Configure the proxy for the wrapper

Pass Java proxy properties so the wrapper JVM routes the download through the corporate proxy.

Terminal

export GRADLE_OPTS="-Dhttps.proxyHost=proxy.internal -Dhttps.proxyPort=8080"
./gradlew --version

Cache the wrapper distribution

Persist ~/.gradle/wrapper/dists so the distribution is downloaded once and reused, avoiding repeated egress.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.gradle/wrapper/dists
    key: gradle-dist-${{ hashFiles('**/gradle-wrapper.properties') }}

How to prevent it

Cache ~/.gradle/wrapper/dists so the distribution downloads once.
Configure proxy properties via GRADLE_OPTS on restricted networks.
Mirror the distribution internally and point distributionUrl at it.