What causes "Too much redirects" in HMCL-dev/HMCL?

Check the URL for a redirect loop (e.g. pointing to itself)

Too much redirects

Error message

Too much redirects

What it means

resolveConnection follows HTTP redirects manually (3xx-308 except 306/304) and aborts with this IOException once more than 20 hops occur. A redirect loop or an excessively long redirect chain on the target server is the usual cause.

Solutions

Check the URL for a redirect loop (e.g. pointing to itself)
Try a mirror or alternate download source for the resource

Example fix

// before
url = "http://example.com/download"; // redirects to itself via https hop chain
// after
url = "https://example.com/download"; // final destination, no redirects

Defensive patterns

Strategy: retry

Validate before calling

int redirects = 0;
HttpURLConnection c = (HttpURLConnection) url.openConnection();
while ((c.getResponseCode() >= 300 && c.getResponseCode() <= 308) && ++redirects <= 20)
    c = (HttpURLConnection) new URL(c.getHeaderField("Location")).openConnection();
if (redirects > 20) throw new IOException("redirect loop");

Try / catch

try {
    NetworkUtils.doGet(url);
} catch (IOException e) {
    if (e.getMessage().equals("Too much redirects")) {
        // switch to another mirror / final https URL
    } else throw e;
}

Prevention

Use final https:// URLs directly instead of chained redirectors
Test URL chains with curl -IL before adding mirrors
Avoid login-gated endpoints for automated downloads
Keep session/cookie handling consistent across hops

When it happens

Trigger: GET/download requests to a URL whose server redirects in a loop (A -> B -> A), or chains of more than 20 hops; cookies/sessions lost on each hop causing repeated redirects.

Common situations: Mirror URLs behind misconfigured load balancers; login-gated download endpoints endlessly redirecting to a login page; CDN misroutes after a site migration.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

AI-assisted analysis of HMCL-dev/HMCL@24702dc5a0 (2026-09-10). Data as JSON: /api/errors/360394dfccd00526. Report an issue: GitHub.

Appendix: source

Thrown at HMCLCore/src/main/java/org/jackhuang/hmcl/util/io/NetworkUtils.java:334

int code = conn.getResponseCode();
if (code >= 300 && code <= 308 && code != 306 && code != 304) {
    String newURL = conn.getHeaderField("Location");
    conn.disconnect();

    if (redirect > 20) {
        throw new IOException("Too much redirects");
    }

    WebURL redirectedUrl = WebURL.of(conn.getURL()).resolve(newURL);
    HttpURLConnection redirected = (HttpURLConnection) redirectedUrl.toURL().openConnection();
    properties.forEach((key, value) -> value.forEach(element -> redirected.addRequestProperty(key, element)));
    injectApiKey(redirectedUrl, redirected);
    redirected.setRequestMethod(method);
    conn = redirected;
    ++redirect;
} else {
    break;
}

View on GitHub (pinned to 24702dc5a0)