apache/hadoop · error · IllegalArgumentException

Invalid parameter range: {name} = {value} < {min}

Error message

Invalid parameter range: {name} = {value} < {min}

What it means

ShortParam.checkRange (ShortParam.java:24-40) throws this IllegalArgumentException when a non-null short parameter value is below the subclass minimum. The built-in ShortParam subclasses are ReplicationParam ('replication', min 1, on CREATE/SETREPLICATION) and PermissionParam / UnmaskedPermissionParam ('permission'/'unmasked.permission', min 0 max 01777, parsed radix 8), so the error means replication < 1 or a negative permission octet.

Source

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

 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.hadoop.hdfs.web.resources;

/** 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());
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Send replication >= 1 or omit the parameter to use the server default (dfs.namenode.replication.min / cluster default).
2. Send permissions as non-negative octal, e.g. permission=644; omit for defaults.
3. Clamp computed replication factors to at least 1 at the call site.

Example fix

# before
curl -i -X PUT "http://nn:9870/webhdfs/v1/f?op=CREATE&replication=0&permission=644"
# after
curl -i -X PUT "http://nn:9870/webhdfs/v1/f?op=CREATE&replication=2&permission=644"

static short checkedReplication(Short r) {
  if (r == null) return -1;                    // omit param -> cluster default
  if (r < 1) throw new IllegalArgumentException("replication must be >= 1: " + r);
  return r;
}
static short checkedPermission(short p) {
  if (p < 0) throw new IllegalArgumentException("permission must be >= 0 (octal): " + Integer.toOctalString(p));
  return p;
}

static boolean isShortInRange(Short v, short min, short max) { return v == null || (v >= min && v <= max); }

When it happens

Trigger: CREATE or SETREPLICATION with ?replication=0 or a negative number; ?permission=-1; ?unmasked.permission=-644; permission=5-11 (malformed arithmetic producing a negative after parse).

Common situations: Using 0 as 'use default replication' — WebHDFS wants the parameter omitted for that, not 0; permission strings with a leading '-' copied from chmod error output; scripts that compute replication = availableNodes - N and go negative on small clusters.

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} > {max}

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