Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Gradle sync fails with 'Could not HEAD' and status code 502 Bad Gateway

ErrorCould not HEAD '...'. Received status code 502 from server: Bad Gateway

Short answer

The server at the URL in the message, or a proxy in front of it, answered Gradle with 502. Gradle retries, then stops using that repository for the rest of the build, so the sync fails. Request the same URL yourself. If it fails for everyone, wait or contact the repository owner. If it works elsewhere, check your proxy settings.

  • Applies to Gradle 8.x and 9.x, Android Studio, Android Gradle plugin 8.x and 9.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Copy the URL from the error and ask for its headers with the same kind of request Gradle made (HEAD). Run it from the machine that fails, then from another network or machine if you can.

    curl -I "https://repo.example.com/path-from-the-error"
  2. 2Match what you see, then jump to its fix

    1. 1The request from the first step also returns 502, and it does so from a second network tooThe repository, or a mirror in front of it, is returning 502Fix
    2. 2The same URL works from another network, a phone hotspot or another machine, but fails from yoursA proxy on your network answers with 502Fix

What does the error look like?

  • Could not HEAD '...'. Received status code 502 from server: Bad Gateway
  • Gradle sync failed

Cause 1 of 2

The repository, or a mirror in front of it, is returning 502

1Check

MDN describes 502 as a server acting as a gateway or proxy that received an invalid response from the upstream server, and says fixing it probably requires the server owners. Gradle's documentation lists HTTP 5xx responses as one of the reasons it disables a repository: it retries errors that may be temporary, with increasing wait times, and then no longer checks that repository for the rest of the build.

curl -I "https://repo.example.com/path-from-the-error"
grep -rn "url" settings.gradle* build.gradle* 2>/dev/null | head -20

2Fix

If the repository is a public one, wait and run the sync again, because the failure is on its side. If it is your own mirror or artifact server, give its administrator the URL and the time of the failure. Do not remove the repository from the build to make the error disappear; Gradle's documentation says that continuing without it could give different results once it is back online.

./gradlew build

3Verify

The same request now returns a success status, and the sync completes.

curl -I "https://repo.example.com/path-from-the-error"

Confirmed by docs.gradle.org

Did this fix it?

Cause 2 of 2

A proxy on your network answers with 502

1Check

MDN says that when the service works for other visitors, clients should check network settings, firewall setup, proxy settings and DNS. Gradle reads its proxy settings from system properties that can be set in gradle.properties.

grep -rn "proxy" gradle.properties ~/.gradle/gradle.properties 2>/dev/null

2Fix

Make the proxy properties match the proxy you really use, remove ones that point to a proxy that no longer exists, and list hosts that must bypass the proxy in nonProxyHosts. The Gradle networking documentation shows the property names.

# gradle.properties
systemProp.https.proxyHost=proxy.example.com
systemProp.https.proxyPort=8080
systemProp.http.nonProxyHosts=*.internal.example.com|localhost

3Verify

Sync again from the same network.

./gradlew build

Confirmed by docs.gradle.org

Did this fix it?

How do I stop it coming back?

  • Read the URL in the message first: it shows whether the failing host is a public repository, your own mirror or a proxy.
  • Keep proxy settings in one gradle.properties file instead of copying them into every project.
  • Re-run a failed sync once before you change the build, so you know whether the failure lasts.
  • Do not hide a failing repository by deleting it from the build; fix it or replace it on purpose.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Android Studio cannot pair the phone over Wi-Fi

The Pair devices over Wi-Fi dialog lists no device

Wireless pairing needs the phone on Android 11 or higher and on the same Wi-Fi network as the computer, with current Platform-Tools.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.