apache/hadoop · error · IllegalArgumentException

Invalid value: "{str}" does not belong to the domain {domain

Error message

Invalid value: "{str}" does not belong to the domain {domain}

What it means

StringParam.Domain.parse (StringParam.java:47-57) enforces an optional regular expression attached to each string-valued WebHDFS/HttpFS parameter; when pattern.matcher(str).matches() is false it throws this IllegalArgumentException, printing the regex as the domain. Affected parameters include user.name (UserParam, default pattern '^[A-Za-z_][A-Za-z0-9._-]*[$]?$' from DFS_WEBHDFS_USER_PATTERN_DEFAULT), HttpFS's filter (listStatus glob), owner/group, xattr names, and aclspec. The server returns HTTP 400.

Source

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

  static final class Domain extends Param.Domain<String> {
    /** The pattern defining the domain; null . */
    private final Pattern pattern;

    Domain(final String paramName, final Pattern pattern) {
      super(paramName);
      this.pattern = pattern;
    }

    @Override
    public final String getDomain() {
      return pattern == null ? "<String>" : pattern.pattern();
    }

    @Override
    final String parse(final String str) {
      if (str != null && pattern != null) {
        if (!pattern.matcher(str).matches()) {
          throw new IllegalArgumentException("Invalid value: \"" + str
              + "\" does not belong to the domain " + getDomain());
        }
      }
      return str;
    }
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Conform the value to the regex printed in the error message — for user.name that means start with a letter/underscore and use only letters, digits, '.', '_', '-', with an optional trailing '$'.
2. If legitimate usernames are being rejected, adjust the pattern: set dfs.webhdfs.user.pattern on the WebHDFS endpoint to a regex that admits them (UserParam.setUserPattern applies it).
3. For SETOWNER/xattr/ACL calls, validate the value against the same rules the corresponding *Param class compiles.

Example fix

# before
curl -i "http://nn:9870/webhdfs/v1/f?op=GETFILESTATUS&user.name=svc/etl@CORP"
# after
curl -i "http://nn:9870/webhdfs/v1/f?op=GETFILESTATUS&user.name=svc_etl"
# (or set -D dfs.webhdfs.user.pattern='^.*@CORP$' style regex on the server)

static final Pattern USER = Pattern.compile("^[A-Za-z_][A-Za-z0-9._-]*[$]?$");
static String checkedUser(String u) {
  if (!USER.matcher(u).matches()) throw new IllegalArgumentException("user.name rejected by WebHDFS pattern: " + u);
  return u;
}

static boolean matchesUserPattern(String u) { return u != null && USER.matcher(u).matches(); }

When it happens

Trigger: user.name='root:adm' or 'user@corp/x' (colon, slash, '@' outside the trailing $ not allowed by the default pattern); owner/group values with spaces or commas in SETOWNER via HttpFS; xattrname not matching the name pattern in SETXATTR; filter containing raw glob metacharacters rejected by the HttpFS filter regex; aclspec with malformed entries in SETACL/MODIFYACLENTRIES.

Common situations: Service accounts with unusual characters in names hitting the WebHDFS user pattern; hardening deployments that tightened dfs.webhdfs.user.pattern and suddenly rejecting previously working user.name values; passing DNs/emails as owner; HttpFS fronting non-HDFS file systems where ACL specs differ.

Related errors

• Failed to parse "{str}" for the parameter {varName}. The va
• Bad rule definition: {bad_lines}
• Failed to parse "{str}" to Boolean.
• {str} is not a valid DELETE operation.
• Invalid parameter value: destination = "{str}" is not an abs

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