apache/hadoop · error · IllegalArgumentException

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

Error message

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

What it means

LongParam is the base class for WebHDFS 64-bit query parameters; checkRange (LongParam.java:24-40) throws this IllegalArgumentException when a non-null value is below the subclass minimum. Concrete floors in this codebase: offset >= 0 and length >= 0 (OPEN/APPEND reads and CREATE lengths), newlength >= 0 (TRUNCATE), blocksize >= 1 (CREATE), modificationtime/accesstime >= -1 (SETTIMES, where -1 means 'do not change'), and namespace/storagespace quota >= QUOTA_RESET (-1, SETQUOTA/SETQUOTABYSTORAGETYPE).

Source

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

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

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

  private void checkRange(final Long min, final Long 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 String getValueString() {
    return domain.toString(getValue());
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Raise the value to the parameter's floor: offset/length/newlength >= 0, blocksize >= 1, times >= -1, quotas >= -1.
2. To express 'not specified', omit the parameter (or send 'null') instead of a negative sentinel.
3. For SETTIMES use -1 only, never lower; for quota reset send -1 (QUOTA_RESET).

Example fix

# before
curl -i -X PUT "http://nn:9870/webhdfs/v1/f?op=TRUNCATE&newlength=-1"
# after
curl -i -X PUT "http://nn:9870/webhdfs/v1/f?op=TRUNCATE&newlength=0"

static long checkedLong(String name, Long v, long min) {
  if (v == null) return min == 0 ? 0L : -1L;   // use each param's documented default
  if (v < min) throw new IllegalArgumentException(name + " must be >= " + min + ": " + v);
  return v;
}

static boolean isNonNegative(Long v) { return v == null || v >= 0L; }

When it happens

Trigger: ?op=OPEN&offset=-1; ?op=CREATE&length=-100; ?op=TRUNCATE&newlength=-1; ?op=CREATE&blocksize=0; ?op=SETTIMES&modificationtime=-2; ?op=SETQUOTA&namespacequota=-2.

Common situations: Passing -1 as an 'unset/skip' sentinel to parameters whose floor is 0 (offset, length, newlength, blocksize); computing sizes as long that underflows; quota scripts that send -2 where -1 (reset quota) was intended.

Related errors

• Invalid parameter range: {name} = {value} > {max}
• Invalid parameter range: {name} = {value} < {min}
• Invalid parameter range: {name} = {value} > {max}
• Failed to parse "{str}" as a radix-{radix} long integer.
• Invalid parameter range: {name} = {value} < {min}

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