apache/hadoop · error · IllegalArgumentException

maxRetries = ${maxRetries} < 0

Error message

maxRetries = ${maxRetries} < 0

What it means

RetryLimited is the base of Hadoop's bounded retry policies (RetryUpToMaximumCountWithFixedSleep and friends). Its constructor fails fast when maxRetries < 0: a negative retry count is never a valid policy, only a programming or configuration error, and the exception names the offending value.

Source

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

  
  /**
   * Retry up to maxRetries.
   * The actual sleep time of the n-th retry is f(n, sleepTime),
   * where f is a function provided by the subclass implementation.
   *
   * The object of the subclasses should be immutable;
   * otherwise, the subclass must override hashCode(), equals(..) and toString().
   */
  static abstract class RetryLimited implements RetryPolicy {
    final int maxRetries;
    final long sleepTime;
    final TimeUnit timeUnit;
    
    private String myString;

    RetryLimited(int maxRetries, long sleepTime, TimeUnit timeUnit) {
      if (maxRetries < 0) {
        throw new IllegalArgumentException("maxRetries = " + maxRetries+" < 0");
      }
      if (sleepTime < 0) {
        throw new IllegalArgumentException("sleepTime = " + sleepTime + " < 0");
      }

      this.maxRetries = maxRetries;
      this.sleepTime = sleepTime;
      this.timeUnit = timeUnit;
    }

    @Override
    public RetryAction shouldRetry(Exception e, int retries, int failovers,
        boolean isIdempotentOrAtMostOnce) throws Exception {
      if (retries >= maxRetries) {
        return new RetryAction(RetryAction.RetryDecision.FAIL, 0 , getReason());
      }
      return new RetryAction(RetryAction.RetryDecision.RETRY,
          timeUnit.toMillis(calculateSleepTime(retries)), getReason());

View on GitHub (pinned to 2add963021)

Solutions

1. Find the value's origin: log the parsed config property before constructing the policy.
2. Validate/clamp user-supplied retry counts at the config layer and reject negatives with the property name in the message.
3. Check the argument order against the factory signature (maxRetries, sleepTime, timeUnit) — swapped args are a classic cause.

Example fix

// before
RetryPolicy p = RetryPolicies.retryUpToMaximumCount(-1, 1, TimeUnit.SECONDS);

// after
int retries = Math.max(0, conf.getInt("my.retries", 3));
RetryPolicy p = RetryPolicies.retryUpToMaximumCount(retries, 1, TimeUnit.SECONDS);

int maxRetries = conf.getInt("my.retries", 3);
if (maxRetries < 0) {
  throw new IllegalArgumentException(
      "my.retries must be >= 0, got " + maxRetries);
}

When it happens

Trigger: Constructing any RetryLimited-based policy (e.g. RetryPolicies.retryUpToMaximumCount) with a negative count — typically a parsed config value the user set negative, or arithmetic like retries - 1 dipping below zero.

Common situations: Site.xml with a negative retry property; policy values computed from capacity math without a floor; arguments passed in the wrong order (sleepTime where maxRetries goes), which the next guard may also catch.

Related errors

• sleepTime = ${sleepTime} < 0
• numRetries = ${numRetries} < 0
• sleepMillis = ${sleepMillis} < 0
• pairs must be neither null nor empty.
• min sleep time must be positive number and max sleep time mu

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