apache/hadoop · error · IllegalArgumentException

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

Error message

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

What it means

Check.gt0(long value, String name) (Check.java:162) throws this IllegalArgumentException when value <= 0: the number must be strictly positive. It is a precondition helper of the httpfs lib framework for sizes, ports, timeouts, and similar counts; the int overload delegates to the long one, so the same error fires for non-positive ints.

Source

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

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

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

  /**
   * Verifies an integer 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 integer is greater or equal to zero.
   */
  public static int ge0(int value, String name) {
    return (int) ge0((long) value, name);
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Set the source configuration property to a positive value.
2. Replace the 0/-1 'unset' sentinel with a real positive default at the conf.get call site.
3. If zero is a valid state in your flow, use Check.ge0 instead of gt0.
4. Validate the value where it is loaded (fail fast with the property name), not deep in call stacks.

Example fix

// before
long port = conf.getLong("service.port", 0); // unset -> 0
Check.gt0(port, "service.port"); // throws: must be greater than zero

// after
long port = conf.getLong("service.port", 14000); // positive default
Check.gt0(port, "service.port"); // ok

long port = conf.getLong("service.port", 0);
if (port <= 0) {
  throw new ConfigurationException("service.port must be > 0, got " + port);
}

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

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

When it happens

Trigger: Check.gt0(0, "port") or Check.gt0(-1, "buffer.size"), typically because a backing config property was unset and the code passed its 0/-1 sentinel into the check instead of a real default.

Common situations: An optional property defaulting to 0; -1 used as a 'not configured' sentinel reaching the validator; arithmetic that legitimately produces 0 (a count of items) but flows into a strictly-positive precondition.

Related errors

• parameter [{0}] = [{1}] must be greater than or equals 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/6b8c4e3485128246. Report an issue: GitHub.