apache/hadoop · error · IllegalArgumentException

parameter [{0}] = [{1}] must be greater than or equals zero

Error message

parameter [{0}] = [{1}] must be greater than or equals zero

What it means

Check.ge0(long value, String name) (Check.java:194) throws this IllegalArgumentException when value < 0: the number must be non-negative (zero is allowed). Like gt0, it is an httpfs lib precondition helper; the int overload delegates to the long one.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/util/Check.java:196

   * @throws IllegalArgumentException if the integer is greater or equal to zero.
   */
  public static int ge0(int value, String name) {
    return (int) ge0((long) value, name);
  }

  /**
   * Verifies an long is greater or equal to zero.
   *
   * @param value integer value.
   * @param name the name to use in the exception message.
   *
   * @return the value.
   *
   * @throws IllegalArgumentException if the long is greater or equal to zero.
   */
  public static long ge0(long value, String name) {
    if (value < 0) {
      throw new IllegalArgumentException(MessageFormat.format(
        "parameter [{0}] = [{1}] must be greater than or equals zero", name, value));
    }
    return value;
  }

}

View on GitHub (pinned to 2add963021)

Solutions

1. Use 0 instead of -1 as the default/unset value for fields validated with ge0.
2. Clamp or reject negative user input at the API boundary before it reaches the check.
3. If -1 is a meaningful sentinel in your code, skip the ge0 call for the unset case.
4. Add unit tests for 0 (valid) and -1 (throws) to lock the semantics.

Example fix

// before
long newLength = conf.getLong("truncate.length", -1L);
Check.ge0(newLength, "truncate.length"); // throws: must be >= zero

// after
long newLength = conf.getLong("truncate.length", 0L);
Check.ge0(newLength, "truncate.length"); // ok

long offset = opts.get("offset", -1L);
if (offset < 0) {
  throw new IllegalArgumentException("offset must be >= 0, got " + offset);
}

static boolean isNonNegative(long v) { return v >= 0; }

try {
  Check.ge0(value, name);
} catch (IllegalArgumentException ex) {
  throw new ConfigurationException("Invalid config value: " + ex.getMessage(), ex);
}

When it happens

Trigger: Check.ge0(-1, "offset") or any negative long/int, commonly because a 'not set' sentinel of -1 (e.g. an offset or default mtime of -1) reaches a field where negative values are meaningless.

Common situations: -1 'unset' sentinels flowing into fields that accept zero; subtraction underflow producing a negative count; user-supplied negative numbers not validated at the boundary.

Related errors

• parameter [{0}] = [{1}] must be greater than zero
• [{0}] = [{1}] exceeds max len [{2}]
• [{0}] = [{1}] must be "{2}"
• Parameter [{0}], invalid value [{1}], value must be [{2}]
• Invalid value

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