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

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.