apache/hadoop · error · IllegalArgumentException

Failed to parse "{str}" to Boolean.

Error message

Failed to parse "{str}" to Boolean.

What it means

BooleanParam.Domain.parse accepts only the case-insensitive literals 'true' and 'false'; any other string in a WebHDFS URL boolean parameter throws IllegalArgumentException('Failed to parse "<str>" to Boolean.'). WebHDFS encodes FileSystem options as HTTP query params (overwrite, recursive, createparent, noredirect, ...), and this parser is used when those param values are materialized from URL strings. Values like 1/0, yes/no, or ON are rejected.

Source

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

  /** The domain of the parameter. */
  static final class Domain extends Param.Domain<Boolean> {
    Domain(final String paramName) {
      super(paramName);
    }

    @Override
    public String getDomain() {
      return "<" + NULL + " | boolean>";
    }

    @Override
    Boolean parse(final String str) {
      if (TRUE.equalsIgnoreCase(str)) {
        return true;
      } else if (FALSE.equalsIgnoreCase(str)) {
        return false;
      }
      throw new IllegalArgumentException("Failed to parse \"" + str
          + "\" to Boolean.");
    }
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Use only true or false (any case) as the value of boolean query params, or omit the param to take its default
2. Prefer the FileSystem API (FileSystem.mkdirs/rename/create with options) — it builds correctly encoded URLs for you
3. Normalize/validate boolean inputs before embedding them in URLs (see validation code)
4. URL-encode values and double-check the param name spelled exactly as the op expects

Example fix

// before
String url = "http://nn:9870/webhdfs/v1/user/x?op=MKDIRS&recursive=1"; // 400: Failed to parse "1" to Boolean
// after
String url = "http://nn:9870/webhdfs/v1/user/x?op=MKDIRS&recursive=true";

static String toWebhdfsBoolean(String raw) {
  if ("true".equalsIgnoreCase(raw) || "false".equalsIgnoreCase(raw)) {
    return raw.toLowerCase(Locale.ROOT);
  }
  throw new IllegalArgumentException(
      "WebHDFS boolean params accept only true/false, got: " + raw);
}

static boolean isBooleanParamValue(String s) {
  return s != null && ("true".equalsIgnoreCase(s) || "false".equalsIgnoreCase(s));
}

try {
  conn.connect();
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("to Boolean")) {
    // URL boolean param was invalid: fix the query string, do not retry
  }
}

When it happens

Trigger: Hand-building a WebHDFS REST URL with a boolean param spelled wrongly, e.g. ...?op=MKDIRS&recursive=1 or ?op=CREATE&overwrite=yes; or programmatically constructing BooleanParam-style params from unchecked user input. Server-side (NameNode/httpfs) the parse failure surfaces as an HTTP 400 with the IllegalArgumentException message.

Common situations: Scripts and curl clients translating CLI flags (0/1, yes/no) directly into WebHDFS URLs; clients porting from S3/GS query conventions; typo'd values (TRUE works, but 'ture' does not); passing empty values (&overwrite=).

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• {str} is not a valid DELETE operation.
• Invalid parameter value: destination = "{str}" is not an abs
• {str} is not a valid GET operation.
• Invalid parameter range: {name} = {value} < {min}
• Invalid parameter range: {name} = {value} > {max}

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