apache/hadoop · error · IllegalArgumentException

Parameter [ ], invalid value [ ], value must be [ ]

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.

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 Operation [ ]
• Invalid value [ ], must be a boolean
• Missing Operation parameter
• Parameter [ ], invalid value [ ], value must be [ ]
• [ ] = [ ] exceeds max len [ ]

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

Appendix: 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)