apache/hadoop · error · IllegalArgumentException

pairs must be neither null nor empty.

Error message

pairs must be neither null nor empty.

What it means

MultipleLinearRandomRetry needs at least one (numRetries, sleepMillis) pair; constructing it with null or an empty list throws immediately. An empty schedule has no retry behavior, and Hadoop treats that as a configuration error rather than 'never retry' — dedicated policies exist for that intent.

Source

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

          throw new IllegalArgumentException("sleepMillis = " + sleepMillis + " < 0");
        }

        this.numRetries = numRetries;
        this.sleepMillis = sleepMillis;
      }
      
      @Override
      public String toString() {
        return numRetries + "x" + sleepMillis + "ms";
      }
    }

    private final List<Pair> pairs;
    private String myString;

    public MultipleLinearRandomRetry(List<Pair> pairs) {
      if (pairs == null || pairs.isEmpty()) {
        throw new IllegalArgumentException("pairs must be neither null nor empty.");
      }
      this.pairs = Collections.unmodifiableList(pairs);
    }

    @Override
    public RetryAction shouldRetry(Exception e, int curRetry, int failovers,
        boolean isIdempotentOrAtMostOnce) throws Exception {
      final Pair p = searchPair(curRetry);
      if (p == null) {
        //no more retries.
        return new RetryAction(RetryAction.RetryDecision.FAIL, 0 , "Retry " +
            "all pairs in MultipleLinearRandomRetry: " + pairs);
      }

      //calculate sleep time and return.
      // ensure 0.5 <= ratio <=1.5
      final double ratio = ThreadLocalRandom.current().nextDouble() + 0.5;
      final long sleepTime = Math.round(p.sleepMillis * ratio);

View on GitHub (pinned to 2add963021)

Solutions

1. If the intent is 'no retries', use RetryPolicies.TRY_ONCE_THEN_FAIL (or noRetry) instead of an empty MultipleLinearRandomRetry.
2. Default the spec when blank — e.g. fall back to the standard '10000,6,60000,10' rather than constructing from nothing.
3. Validate pairs != null && !pairs.isEmpty() before construction and include the raw spec string in the error.

Example fix

// before
RetryPolicy p = new MultipleLinearRandomRetry(Collections.emptyList());

// after
RetryPolicy p = pairs == null || pairs.isEmpty()
    ? RetryPolicies.TRY_ONCE_THEN_FAIL
    : new MultipleLinearRandomRetry(pairs);

if (pairs == null || pairs.isEmpty()) {
  throw new IllegalArgumentException(
      "retry spec produced no pairs: '" + rawSpec + "'");
}

When it happens

Trigger: Parsing a retry spec that is empty or whose tokens all fail to parse, leaving an empty list; programmatic list construction inside a loop that never executes; refactors leaving a stub list behind.

Common situations: dfs.client.retry.policy.spec set to '' or to a value the parser cannot tokenize; conditional code paths that append pairs only when features are enabled, producing zero pairs.

Related errors

• maxRetries = ${maxRetries} < 0
• sleepTime = ${sleepTime} < 0
• numRetries = ${numRetries} < 0
• sleepMillis = ${sleepMillis} < 0
• 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/6e4747a1e1d255b6. Report an issue: GitHub.