apache/hadoop · error · IllegalArgumentException

Invalid value [{0}], must be a boolean

Error message

Invalid value [{0}], must be a boolean

What it means

org.apache.hadoop.lib.wsrs.BooleanParam.parse (BooleanParam.java:39) accepts only the case-insensitive literals "true" and "false" for REST query parameters; anything else throws IllegalArgumentException("Invalid value [...], must be a boolean"). In httpfs, BooleanParam backs the WebHDFS query parameters data, noredirect, recursive, overwrite and allusers (HttpFSParametersProvider). Note that on the normal JAX-RS path this exception is caught by Param.parseParam and rewrapped as the 'Parameter [...], invalid value [...], value must be [a boolean]' message (error 3685), so the raw text surfaces only when parse() is called directly, e.g. in unit tests.

Source

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

import org.apache.hadoop.classification.InterfaceAudience;

import java.text.MessageFormat;

@InterfaceAudience.Private
public abstract class BooleanParam extends Param<Boolean> {

  public BooleanParam(String name, Boolean defaultValue) {
    super(name, defaultValue);
  }

  @Override
  protected Boolean parse(String str) throws Exception {
    if (str.equalsIgnoreCase("true")) {
      return true;
    } else if (str.equalsIgnoreCase("false")) {
      return false;
    }
    throw new IllegalArgumentException(MessageFormat.format("Invalid value [{0}], must be a boolean", str));
  }

  @Override
  protected String getDomain() {
    return "a boolean";
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Send only true or false (case-insensitive) for boolean params: recursive=true, overwrite=false.
2. Fix the client serializer to emit boolean literals, never 1/0/yes/no.
3. Trim and URL-decode values before building the request URL.
4. For custom BooleanParam subclasses invoked directly, keep the parse() contract: true/false only.

Example fix

# before
curl 'http://nn:14000/webhdfs/v1/dir?op=DELETE&user.name=hdfs&recursive=1'   # 400

# after
curl 'http://nn:14000/webhdfs/v1/dir?op=DELETE&user.name=hdfs&recursive=true' # 200

String v = queryParams.get("recursive");
if (v != null && !v.equalsIgnoreCase("true") && !v.equalsIgnoreCase("false")) {
  throw new IllegalArgumentException("recursive must be true|false, got " + v);
}

static boolean isBooleanLiteral(String s) {
  return "true".equalsIgnoreCase(s) || "false".equalsIgnoreCase(s);
}

try {
  param.parseParam(value);
} catch (IllegalArgumentException ex) {
  // message already states the domain ('a boolean'); map to HTTP 400
  return badRequest(ex.getMessage());
}

When it happens

Trigger: A WebHDFS/httpfs request like ?op=DELETE&recursive=1 or ?op=CREATE&overwrite=yes — '1', '0', 'yes', 'no', 'on' are all rejected; only true/false (any case) pass. Directly calling parse("1") on a BooleanParam subclass in tests reproduces the raw message.

Common situations: Scripts ported from shell conventions where 0/1 mean false/true; clients sending 'Yes'/'on'; URL-encoding damage appending %0A or spaces to the value.

Related errors

• Parameter [{0}], invalid value [{1}], value must be [{2}]
• Missing Operation parameter [{0}]
• Invalid Operation [{0}]
• Parameter [{0}], invalid value [{1}], value must be [{2}]
• The length to read ${length} exceeds the file length ${fin.l

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