apache/hadoop · error · IllegalArgumentException

Parameter [{0}], invalid value [{1}], value must be [{2}]

Error message

Parameter [{0}], invalid value [{1}], value must be [{2}]

What it means

Param.parseParam(String) (Param.java:43) is the generic query-parameter entry point of the httpfs wsrs framework: it trims the input, delegates to the subclass's protected parse(), and on ANY exception rethrows IllegalArgumentException("Parameter [name], invalid value [str], value must be [domain]"), where the domain comes from getDomain() ('a long', 'a short', 'a boolean', or a regex). This is how malformed WebHDFS query values become HTTP 400 responses, and it wraps the specific parse failures such as errors 3684 and 3691.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/wsrs/Param.java:43

@InterfaceAudience.Private
public abstract class Param<T> {
  private String name;
  protected T value;

  public Param(String name, T defaultValue) {
    this.name = name;
    this.value = defaultValue;
  }

  public String getName() {
    return name;
  }

  public T parseParam(String str) {
    try {
      value = (str != null && str.trim().length() > 0) ? parse(str) : value;
    } catch (Exception ex) {
      throw new IllegalArgumentException(
        MessageFormat.format("Parameter [{0}], invalid value [{1}], value must be [{2}]",
                             name, str, getDomain()));
    }
    return value;
  }

  public T value() {
    return value;
  }

  protected abstract String getDomain();

  protected abstract T parse(String str) throws Exception;

  @Override
  public String toString() {
    return (value != null) ? value.toString() : "NULL";
  }

View on GitHub (pinned to 2add963021)

Solutions

1. Send the value in the form the error's 'value must be' clause states: a long, a short, a boolean, or matching the printed regex.
2. Fix client serialization: no units, no thousands separators, no trailing whitespace or newlines.
3. For custom Param subclasses, implement getDomain() precisely so the 400 is self-documenting.
4. URL-encode parameter values correctly and avoid stray whitespace in generated URLs.

Example fix

# before
?op=SETREPLICATION&replication=double
# 400: Parameter [replication], invalid value [double], value must be [a long]

# after
?op=SETREPLICATION&replication=2

String raw = params.get("replication");
if (raw != null) {
  try { Long.parseLong(raw.trim()); }
  catch (NumberFormatException e) { throw new IllegalArgumentException("replication must be a long: " + raw); }
}

try {
  param.parseParam(str);
} catch (IllegalArgumentException ex) {
  // the message names the parameter, the bad value, and the required domain
  throw new BadRequestException(ex.getMessage(), ex);
}

When it happens

Trigger: Any httpfs/WebHDFS REST call with a valid op but a malformed typed parameter: replication=abc (LongParam), permission=99999 (ShortParam overflow), modifiedtime=xyz, recursive=1 (BooleanParam). Each surfaces as a 400 whose body names the parameter, the bad value, and the required domain.

Common situations: Clients serializing numbers with units or separators ('10s', '1,000'); strings sent where numbers are expected; typo'd values; custom embedders forgetting to override getDomain(), leaving a vague hint in the 400 body.

Related errors

• Invalid value [{0}], must be a boolean
• Missing Operation parameter [{0}]
• Invalid Operation [{0}]
• Parameter [{0}], invalid value [{1}], value must be [{2}]
• Invalid DFS directory name ${result}

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