apache/hadoop · error · IllegalArgumentException

Failed to parse "{str}" for the parameter {varName}. The va

Error message

Failed to parse "{str}" for the parameter {varName}.  The value must be in the domain {domain}

What it means

This is the generic wrapper in Param.Domain.parse (Param.java:109-120): every WebHDFS/HttpFS parameter type (boolean, enum, enum-set, string-pattern, numeric) implements parse(str), and the framework's two-argument parse(varName, str) catches any exception from it and rethrows IllegalArgumentException enriched with the parameter name and its domain string. Seeing it means a query parameter failed type-specific parsing; the parameter name and allowed domain are printed in the message, and the original cause (e.g. BooleanParam's parse error) is attached.

Source

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

    /** @return the parameter name. */
    public final String getParamName() {
      return paramName;
    }

    /** @return a string description of the domain of the parameter. */
    public abstract String getDomain();

    /** @return the parameter value represented by the string. */
    abstract T parse(String str);

    /** Parse the given string.
     * @return the parameter value represented by the string.
     */
    public final T parse(final String varName, final String str) {
      try {
        return str != null && str.trim().length() > 0 ? parse(str) : null;
      } catch(Exception e) {
        throw new IllegalArgumentException("Failed to parse \"" + str
            + "\" for the parameter " + varName
            + ".  The value must be in the domain " + getDomain(), e);
      }
    }
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Read the message: it states which parameter ('the parameter X') and the exact allowed domain, e.g. <true|false> or the enum list — conform the value to it.
2. Use true/false lowercase for boolean parameters; use exact enum constant names for enum parameters.
3. Check the cause chain in the logs if you wrap requests server-side; the nested exception names the real parse failure.

Example fix

# before
curl -i -X PUT "http://nn:9870/webhdfs/v1/dir?op=MKDIRS&recursive=yes"
# after
curl -i -X PUT "http://nn:9870/webhdfs/v1/dir?op=MKDIRS&recursive=true"

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

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

try {
  call();
} catch (IOException e) {
  if (e.getMessage() != null && e.getMessage().contains("The value must be in the domain")) {
    // message names the parameter and its domain; fix the value and do not retry
  }
}

When it happens

Trigger: ?overwrite=maybe or ?recursive=yes (BooleanParam accepts only true/false); ?xattrsetflag=REPLACEX (EnumSetParam of XAttrSetFlag: CREATE/REPLACE); ?renameoptions=KEEP& (EnumSetParam RenameOptionSet); any enum-backed parameter fed a value outside its constants; HttpFS/WebHDFS server-side parameter binding of the same.

Common situations: Scripts using 'yes'/'no' or '1'/'0' instead of 'true'/'false' for overwrite, recursive, noredirect; invalid enum tokens in ACL/xattr calls; clients ported from other REST APIs that assume permissive boolean parsing.

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

• Bad rule definition: {bad_lines}
• {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}

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