apache/hadoop · error · IllegalArgumentException

Invalid parameter range: {name} = {value} > {max}

Error message

Invalid parameter range: {name} = {value} > {max}

What it means

The upper-bound half of ShortParam.checkRange (ShortParam.java:33-39): a non-null short parameter above the subclass maximum throws this IllegalArgumentException (HTTP 400). In practice this is the permission parameters: PermissionParam and UnmaskedPermissionParam both declare max 01777 (octal 1023, i.e. setuid+setgid+sticky plus rwxrwxrwx), parsed in radix 8. A permission octet with an extra leading digit beyond 1777 exceeds the range.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/resources/ShortParam.java:37

/** Short parameter. */
abstract class ShortParam extends Param<Short, ShortParam.Domain> {
  ShortParam(final Domain domain, final Short value,
      final Short min, final Short max) {
    super(domain, value);
    checkRange(min, max);
  }

  private void checkRange(final Short min, final Short max) {
    if (value == null) {
      return;
    }
    if (min != null && value < min) {
      throw new IllegalArgumentException("Invalid parameter range: " + getName()
          + " = " + domain.toString(value) + " < " + domain.toString(min));
    }
    if (max != null && value > max) {
      throw new IllegalArgumentException("Invalid parameter range: " + getName()
          + " = " + domain.toString(value) + " > " + domain.toString(max));
    }
  }

  @Override
  public String toString() {
    return getName() + "=" + domain.toString(getValue());
  }

  /** @return the parameter value as a string */
  @Override
  public final String getValueString() {
    return domain.toString(getValue());
  }

  /** The domain of the parameter. */
  static final class Domain extends Param.Domain<Short> {
    /** The radix of the number. */

View on GitHub (pinned to 2add963021)

Solutions

1. Send at most 01777: use 3-digit octal (644, 755) or special-bit forms up to 1777.
2. If you need to express setuid/setgid/sticky plus rwx, encode within 1777 (e.g. 1755); drop the extra digit.
3. For richer access control use the ACL operations (SETACL/MODIFYACLENTRIES) instead of oversized modes.

Example fix

# before
curl -i -X PUT "http://nn:9870/webhdfs/v1/f?op=CREATE&permission=2775"
# after
curl -i -X PUT "http://nn:9870/webhdfs/v1/f?op=CREATE&permission=775"

static short checkedOctalPermission(String perm) {        // radix-8, <= 01777
  int v = Integer.parseInt(perm, 8);
  if (v < 0 || v > 01777) throw new IllegalArgumentException("permission out of 0..1777 octal: " + perm);
  return (short) v;
}

static boolean isPermissibleOctalMode(String s) {
  if (s == null || !s.matches("[0-7]{1,4}")) return false;
  return Integer.parseInt(s, 8) <= 01777;
}

When it happens

Trigger: ?permission=2000 (octal 1024 > 1023); ?permission=7777; ?unmasked.permission=2755 — any 4-digit octal whose value exceeds 01777; also a decimal-looking value such as permission=888 is a parse error, but permission=1000 through 1777 are valid and above that fails.

Common situations: Copy-pasting 4-digit chmod modes like 2775/4775 as the whole permission — WebHDFS expects at most 3 mode digits plus the special bits within 1777; ACL-style masks mistakenly passed as permission.

Related errors

• Invalid parameter range: {name} = {value} < {min}
• Invalid parameter range: {name} = {value} > {max}
• Invalid parameter range: {name} = {value} < {min}
• Invalid parameter range: {name} = {value} > {max}
• Invalid parameter range: {name} = {value} < {min}

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