{"record":{"id":"09a060b29e232068","repo":"apache/hadoop","slug":"failed-to-parse-str-for-the-parameter-varname","errorCode":null,"errorMessage":"Failed to parse \"{str}\" for the parameter {varName}.  The value must be in the domain {domain}","messagePattern":"Failed to parse \"(.+?)\" for the parameter (.+?)\\.  The value must be in the domain (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/resources/Param.java","lineNumber":116,"sourceCode":"    /** @return the parameter name. */\n    public final String getParamName() {\n      return paramName;\n    }\n\n    /** @return a string description of the domain of the parameter. */\n    public abstract String getDomain();\n\n    /** @return the parameter value represented by the string. */\n    abstract T parse(String str);\n\n    /** Parse the given string.\n     * @return the parameter value represented by the string.\n     */\n    public final T parse(final String varName, final String str) {\n      try {\n        return str != null && str.trim().length() > 0 ? parse(str) : null;\n      } catch(Exception e) {\n        throw new IllegalArgumentException(\"Failed to parse \\\"\" + str\n            + \"\\\" for the parameter \" + varName\n            + \".  The value must be in the domain \" + getDomain(), e);\n      }\n    }\n  }\n}\n","sourceCodeStart":98,"sourceCodeEnd":123,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/web/resources/Param.java#L98-L123","documentation":"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.","triggerScenarios":"?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.","commonSituations":"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.","solutions":["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.","Use true/false lowercase for boolean parameters; use exact enum constant names for enum parameters.","Check the cause chain in the logs if you wrap requests server-side; the nested exception names the real parse failure."],"exampleFix":"# before\ncurl -i -X PUT \"http://nn:9870/webhdfs/v1/dir?op=MKDIRS&recursive=yes\"\n# after\ncurl -i -X PUT \"http://nn:9870/webhdfs/v1/dir?op=MKDIRS&recursive=true\"","handlingStrategy":"validation","validationCode":"static String checkedBoolean(String raw) {\n  if (\"true\".equalsIgnoreCase(raw) || \"false\".equalsIgnoreCase(raw)) return raw.toLowerCase(Locale.ROOT);\n  throw new IllegalArgumentException(\"boolean params accept only true/false: \" + raw);\n}","typeGuard":"static boolean isWebhdfsBoolean(String s) { return \"true\".equalsIgnoreCase(s) || \"false\".equalsIgnoreCase(s); }","tryCatchPattern":"try {\n  call();\n} catch (IOException e) {\n  if (e.getMessage() != null && e.getMessage().contains(\"The value must be in the domain\")) {\n    // message names the parameter and its domain; fix the value and do not retry\n  }\n}","preventionTips":["Use only lowercase true/false for overwrite, recursive, noredirect.","For enum-backed params (xattrsetflag, renameoptions) validate against EnumSet.allOf(...) names.","Keep a whitelist table of parameter -> domain in your client and lint URLs before sending."],"tags":["webhdfs","query-param","validation","httpfs","hdfs"],"backgroundTag":"query-parameter-parse-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}