Maven "transfer failed ... 503 Service Unavailable" in CI

By Kaveh Alemi·Latchkey

The repository answered with HTTP 503, meaning it is temporarily unavailable, overloaded, or rate limiting requests. The request was well formed; the server simply could not serve it at that moment.

What this error means

Resolution or deploy fails with "Could not transfer artifact ...: status code: 503, reason phrase: Service Unavailable (503)". It usually clears on a retry.

mvn output

[ERROR] Failed to execute goal on project app: Could not resolve dependencies:
Could not transfer artifact org.example:lib:jar:1.0.0 from/to central
(https://repo.maven.apache.org/maven2): status code: 503,
reason phrase: Service Unavailable (503) -> [Help 1]

Common causes

The repository is temporarily down or overloaded

A 503 is a server-side, transient state: maintenance, a load spike, or capacity limits, not a problem with your request.

Rate limiting from many parallel jobs

A burst of concurrent CI jobs hitting the same mirror can trip rate limits that return 503.

How to fix it

Retry with backoff

Enable wagon HTTP retries so a transient 503 is retried instead of failing the job.

Terminal

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

Cache and use a mirror to cut load

Cache ~/.m2/repository and resolve through a stable internal mirror to reduce pressure on the public host.

.github/workflows/ci.yml

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

How to prevent it

Cache the local repository to avoid repeated remote hits.
Resolve through a reliable mirror, not the public host directly.
Enable wagon retries for transient 5xx responses.

Frequently asked questions

What causes ""status code: 503 Service Unavailable""?