Maven "Return code is: 501 / 502 / 503" from Repository - Fix in CI

By Daniel Zoghalchali·Latchkey

The repository or a proxy in front of it answered with a 5xx HTTP status. A 502/503 is usually a transient backend hiccup; a 501 typically means a proxy refused the HTTP method Maven used.

What this error means

A transfer fails with Transfer failed for ... Return code is: 501 (or 502/503). Unlike a 401/403, the request reached the server and the server itself errored.

[ERROR] Failed to execute goal ... Could not transfer artifact
org.example:lib:jar:1.0 from/to central (https://repo.example.com/...):
Transfer failed for https://repo.example.com/.../lib-1.0.jar 501 Not Implemented

Common causes

Transient backend error (502/503)

The repository or its load balancer was briefly overloaded or restarting. A 502 Bad Gateway or 503 Service Unavailable typically clears on retry.

Proxy refuses the HTTP method (501)

A 501 Not Implemented often means a forward proxy does not support the method Maven sent (e.g. a HEAD or a tunneled request), or mishandles the URL.

How to fix it

Retry transient 5xx with the wagon

For 502/503, a bounded retry usually succeeds once the backend recovers.

mvn -B -Dmaven.wagon.http.retryHandler.count=3 clean verify

Fix proxy handling for a 501

1. Confirm the proxy supports the methods Maven uses (GET/HEAD).
2. Try resolving directly (bypassing the proxy) to confirm the proxy is the cause.
3. Update the proxy config or use a pull-through mirror that the proxy handles correctly.

How to prevent it

• Resolve through a reliable mirror rather than directly hitting public Central.
• Set wagon retries so transient 5xx do not fail the build.
• Verify the proxy supports the HTTP methods build tools use.

Frequently asked questions

Related guides

References

• Apache Maven guides
• Gradle user manual
• GitHub Actions documentation