apache/hadoop · error · IllegalArgumentException

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

Error message

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

What it means

IntegerParam is the base class for WebHDFS integer query parameters; its constructor runs checkRange() (IntegerParam.java:24-40) and throws this IllegalArgumentException when a non-null value is below the subclass-declared minimum. In this codebase the concrete subclasses are BufferSizeParam (min 1, 'buffersize' on OPEN/CREATE/APPEND) and SnapshotDiffIndexParam (min -1, 'snapshotdiffindex' on GETSNAPSHOTDIFFLISTING), so the error means one of those parameters was sent too small. The server converts it to HTTP 400.

Source

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

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

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

  private void checkRange(final Integer min, final Integer 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. Send buffersize >= 1 (e.g. the common 4096) or omit the parameter entirely — the server falls back to io.file.buffer.size from its config.
2. For snapshotdiffindex, use -1 or omit it to start from the beginning of the diff.
3. Clamp user-supplied sizes at your call site before building the URL.

Example fix

# before
curl -i "http://nn:9870/webhdfs/v1/f?op=OPEN&buffersize=0"
# after
curl -i "http://nn:9870/webhdfs/v1/f?op=OPEN&buffersize=4096"

static int checkedBufferSize(Integer v) {
  if (v == null) return 4096;                 // omit param, server default applies
  if (v < 1) throw new IllegalArgumentException("buffersize must be >= 1: " + v);
  return v;
}

static boolean isInRange(Integer v, int min) { return v == null || v >= min; }

When it happens

Trigger: OPEN/CREATE with ?buffersize=0 or a negative buffersize; GETSNAPSHOTDIFFLISTING with ?snapshotdiffindex=-2 (the -1 sentinel meaning 'from the beginning' is the floor).

Common situations: Passing io.file.buffer.size=0 from config straight into a WebHDFS URL; tools that let users type a buffer size without clamping; arithmetic that computes a size and underflows to 0 or negative before the request.

Related errors

• Invalid parameter range: {name} = {value} > {max}
• Failed to parse "{str}" as a radix-{radix} integer.
• 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/71a60f36b290e906. Report an issue: GitHub.