Maven Central 429 Too Many Requests: build through a proxy
Maven Central has begun to limit very heavy traffic, and it answers that traffic with 429 Too Many Requests.
Sonatype, which runs Maven Central, says the way out is less traffic to Maven Central. This page shows how: send your
Maven or Gradle builds through a CloudRepo proxy repository of Maven Central.
1. Create the proxy repository
Section titled “1. Create the proxy repository”You need a CloudRepo account. If you have none, sign up first. In the
admin portal, open Create repository. Choose Maven as the Format and
Proxy as the Kind. Maven Central is already chosen under Upstream. Name the repository
maven-central, then select Create repository.
Your builds also need a repository token that reaches the proxy. A token with Download packages access is enough.
2. Point Maven at the proxy
Section titled “2. Point Maven at the proxy”<settings> <mirrors> <mirror> <id>cloudrepo</id> <mirrorOf>central</mirrorOf> <url>https://your-org.mycloudrepo.io/repositories/maven-central</url> </mirror> </mirrors> <servers> <server> <id>cloudrepo</id> <username>you@example.com</username> <password>${env.CLOUDREPO_TOKEN}</password> </server> </servers></settings>central is the id Maven gives Maven Central. The <mirror> sends every request for central to the proxy instead,
plugins included. The <server> has the same <id>, and gives Maven the credential: the email
address of the account that created the token, and the token. ${env.CLOUDREPO_TOKEN} reads the token from an
environment variable, so the file holds no token.
3. Build
Section titled “3. Build”mvn --batch-mode packageExpected: Maven’s download lines read Downloaded from cloudrepo: and a URL under
https://your-org.mycloudrepo.io/repositories/maven-central. No line reads Downloaded from central:.
What Maven Central limits
Section titled “What Maven Central limits”Sonatype explains the limits on its page 429 Too Many Requests and Maven Central consumption limits: “Maven Central is beginning to enforce consumption limits for unusually high-volume traffic.”
The limit is not about one build. Sonatype says a 429 “means the aggregate traffic Maven Central sees from your
organization, network, provider, platform, toolchain, or shared egress path has crossed a consumption threshold.” So:
The source of the traffic may not be the build that failed; it may be another part of the same organization, platform, or shared network producing enough aggregate consumption to trigger the limit.
“Rate limit blocks are temporary.” But Sonatype also says: “When the same traffic patterns continue over time, those blocks may become longer.”
What Sonatype says to do
Section titled “What Sonatype says to do”From the same page:
In most cases, the right answer is not to retry harder. More retries usually make the problem worse.
The goal is to reduce unnecessary traffic to Maven Central by caching artifacts, consolidating requests through a repository manager, fixing tools or jobs that bypass caches, and avoiding repeated downloads from clean or ephemeral environments when the same artifacts have already been retrieved.
Sonatype’s page I do not have a repository manager says what one does: “A repository manager sits between your development environment and public package registries like Maven Central.” And: “The first request retrieves the component from the public registry; later requests can be served from cache.”
A CloudRepo proxy repository of Maven Central sits between your builds and Maven Central. Your builds download from CloudRepo. The first time a build asks for a file, CloudRepo fetches it from Maven Central and keeps a copy in the proxy repository. The file your build gets is Maven Central’s own, byte for byte.
Sonatype’s page I already have a repository manager names two checks:
Check whether build agents are provisioned with the correct
settings.xml,init.gradle, mirror configuration, or equivalent package manager settings.
Ensure ephemeral CI runners receive the same repository configuration as long-lived build agents.
So give every job the same settings. In GitHub Actions, commit the file above as .mvn/settings.xml, keep the token
in a GitHub secret named CLOUDREPO_TOKEN, as
Store the token as a secret shows, and pass the file with
--settings:
name: Buildon: pushjobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: actions/setup-java@v4 with: distribution: temurin java-version: "17" - name: Build env: CLOUDREPO_TOKEN: ${{ secrets.CLOUDREPO_TOKEN }} run: mvn --batch-mode --settings .mvn/settings.xml packageGradle
Section titled “Gradle”Add the proxy to the settings file your project already has, settings.gradle.kts or settings.gradle, as the one
repository your dependencies come from. The block is the same in either language.
Do not create a second settings file beside it: Gradle reads only one and ignores the other.
dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { maven { url = uri("https://your-org.mycloudrepo.io/repositories/maven-central") credentials { username = providers.gradleProperty("cloudrepoUsername").get() password = providers.gradleProperty("cloudrepoToken").get() } } }}Set the Gradle properties cloudrepoUsername and cloudrepoToken as
Pull Gradle dependencies from CloudRepo shows, on a laptop and in CI.
Gradle then downloads each dependency from CloudRepo, and the file it gets is Maven Central’s own, byte for byte.
FAIL_ON_PROJECT_REPOS makes a build file that lists a repository of its own fail the build, so remove the
repositories block from your build files. It is the strict choice: a build file that lists its own repository fails
instead of quietly reaching Maven Central, whereas the quick start in the admin portal uses PREFER_SETTINGS, which
ignores such a repository with a warning and does not fail the build. The block is for the dependencies your projects
declare. Gradle takes the repositories for plugins from pluginManagement, which this block does not change.
Build with --info, which prints a Downloading line for each file Gradle downloads:
gradle build --infoExpected: each Downloading line for your dependencies names https://your-org.mycloudrepo.io/repositories/maven-central/
and the file’s path. None names repo.maven.apache.org.
One URL for your artifacts and Maven Central’s
Section titled “One URL for your artifacts and Maven Central’s”Put the proxy in a Maven group repository with your hosted repository. One group URL then serves your own artifacts
and Maven Central’s, and Maven reads every dependency through it with a mirror of *. For the group and its settings,
see
Pull through a group.
More on proxies and their settings: Proxy Repositories.