What causes "Too many redirects (>${MAX_REDIRECTS})" in agalwood/Motrix?

Switch to redirect:'manual' and walk hops explicitly with a visited-set to detect loops.

agalwood/Motrix · error · HttpError

plugin.http.too_many_redirects

plugin.http.too_many_redirects

Error message

Too many redirects (>${MAX_REDIRECTS})

What it means

With redirect:'follow', each 3xx hop increments a counter; when it reaches MAX_REDIRECTS (10) the body is dumped and the request fails. This bounds redirect chains to prevent loops and resource exhaustion.

Source

Thrown at src/core/plugin/capabilities/http.ts:404

              opts.responseType,
              maxBodyBytes,
              internalCtrl,
              currentUrl,
              redirected,
              doCleanup
            )
          }
          if (redirect === 'error') {
            await response.body.dump?.()
            throw new HttpError(
              'plugin.http.redirect_not_allowed',
              `redirect: 'error' set; refusing to follow ${status} to ${location}`
            )
          }
          // redirect === 'follow'
          if (hops >= MAX_REDIRECTS) {
            await response.body.dump?.()
            throw new HttpError(
              'plugin.http.too_many_redirects',
              `Too many redirects (>${MAX_REDIRECTS})`
            )
          }
          await response.body.dump?.()
          const loc = Array.isArray(location) ? (location[0] ?? '') : location
          const nextUrl = new URL(loc, currentUrl)
          // Re-validate the scheme on every hop. checkScheme only ran on the
          // initial URL, so a 3xx Location to file:// (or any non-http scheme)
          // would otherwise escape the allowlist.
          checkScheme(nextUrl)
          currentUrl = nextUrl.toString()
          redirected = true
          hops += 1
          continue
        }

        return await buildResponse<R>(

View on GitHub (pinned to 1a708ee577)

Solutions

Switch to redirect:'manual' and walk hops explicitly with a visited-set to detect loops.
Fix the upstream redirect loop (server config, auth cookie scope, trailing-slash rules).
Use the final, already-resolved URL as the request target.
Set redirect:'error' to fail fast on the first hop if redirects are not expected.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  return await http.request({ ...opts, redirect: 'follow' })
} catch (e) {
  if (e instanceof HttpError && e.code === 'plugin.http.too_many_redirects') {
    // fall back to manual hop-walking with a visited-set to detect the loop
    return await followManually(opts.url)
  }
  throw e
}

Prevention

When following redirects, walk hops manually with a visited-URL set to detect loops fast.
Investigate any change from N hops to >10 hops - it usually indicates a server-side regression.
Pin final URLs at the call site when you know them, to avoid redirect chains entirely.

When it happens

Trigger: A redirect loop (A->B->A); an unusually long legitimate chain (>10 hops); a misconfigured server whose Location points back to itself; cookie/auth loss causing repeated re-auth redirects.

Common situations: Server redirect loop bug; CDN cascading redirects; login flow that bounces between auth providers; URL shortener chains.

Related errors

AI-assisted analysis of agalwood/Motrix@1a708ee577 (2026-08-12). Data as JSON: /api/errors/cc121866cb8a1c84. Report an issue: GitHub.