apache/hadoop · error · IllegalArgumentException

maxRetries = ${maxRetries} >= ${Long.SIZE - 1}

Error message

maxRetries = ${maxRetries} >= ${Long.SIZE - 1}

What it means

ExponentialBackoffRetry computes sleeps via calculateExponentialTime (shift-style exponentials on sleepTime). With maxRetries >= Long.SIZE - 1 (63), the shift can overflow a long and produce negative or nonsensical delays, so the constructor rejects such counts up front. This is an overflow guard, not an opinion about good retry counts — though 63 exponential retries already spans astronomical time.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/io/retry/RetryPolicies.java:635

      if (policy == null) {
        policy = defaultPolicy;
      }
      return policy.shouldRetry(
          e, retries, failovers, isIdempotentOrAtMostOnce);
    }
  }

  static class ExponentialBackoffRetry extends RetryLimited {
    
    public ExponentialBackoffRetry(
        int maxRetries, long sleepTime, TimeUnit timeUnit) {
      super(maxRetries, sleepTime, timeUnit);

      if (maxRetries < 0) {
        throw new IllegalArgumentException("maxRetries = " + maxRetries + " < 0");
      } else if (maxRetries >= Long.SIZE - 1) {
        //calculateSleepTime may overflow. 
        throw new IllegalArgumentException("maxRetries = " + maxRetries
            + " >= " + (Long.SIZE - 1));
      }
    }
    
    @Override
    protected long calculateSleepTime(int retries) {
      return calculateExponentialTime(sleepTime, retries + 1);
    }

  }
  
  /**
   * Fail over and retry in the case of:
   *   Remote StandbyException (server is up, but is not the active server)
   *   Immediate socket exceptions (e.g. no route to host, econnrefused)
   *   Socket exceptions after initial connection when operation is idempotent
   * 
   * The first failover is immediate, while all subsequent failovers wait an

View on GitHub (pinned to 2add963021)

Solutions

1. Cap maxRetries below 63 — 10 to 20 is already generous for exponential backoff.
2. For effectively-unlimited retries over time, use a time-bounded policy such as RetryUpToMaximumTimeWithFixedSleep instead of a huge count.
3. Sanity-check the total sleep the schedule implies (sleepTime * 2^maxRetries) — if it exceeds your operational patience, shrink the count.

Example fix

// before
new ExponentialBackoffRetry(999, 1000, TimeUnit.MILLISECONDS);

// after
int maxRetries = Math.min(conf.getInt("my.retries", 10), 62);
new ExponentialBackoffRetry(maxRetries, 1000, TimeUnit.MILLISECONDS);

int maxRetries = conf.getInt("my.exp.retries", 10);
if (maxRetries >= Long.SIZE - 1) {
  throw new IllegalArgumentException(
      "exponential backoff maxRetries must be < 63, got " + maxRetries);
}

When it happens

Trigger: Configuring exponential backoff with maxRetries >= 63 — commonly someone 'disabling the cap' with Integer.MAX_VALUE, 999, or a value copied from a recipe tuned for a framework that allows unbounded counts.

Common situations: Operators emulating 'retry forever' with a huge count; copied exponential-backoff configs from other libraries; generated configs with sentinel values like 2^31-1.

Related errors

• maxRetries = ${maxRetries} < 0
• sleepTime = ${sleepTime} < 0
• numRetries = ${numRetries} < 0
• sleepMillis = ${sleepMillis} < 0
• pairs must be neither null nor empty.

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/9ad91fd85c3a5e00. Report an issue: GitHub.