apache/hadoop · error · HadoopIllegalArgumentException

Configuration hadoop.user.group.static.mapping.overrides is

Error message

Configuration hadoop.user.group.static.mapping.overrides is invalid

What it means

Groups (Hadoop's group-mapping service) parses hadoop.user.group.static.mapping.overrides at construction. The value is ';'-separated entries, each either 'user' (maps to empty group set) or 'user=group1,group2'. If any entry splits on '=' into zero parts or more than two parts, a HadoopIllegalArgumentException is thrown with this message. This fails fast at first group lookup, so it typically breaks NameNode/DataNode/JobTracker startup or the first UGI group resolution.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/Groups.java:175

    return negativeCache;
  }

  /*
   * Parse the hadoop.user.group.static.mapping.overrides configuration to
   * staticUserToGroupsMap
   */
  private void parseStaticMapping(Configuration conf) {
    String staticMapping = conf.get(
        CommonConfigurationKeys.HADOOP_USER_GROUP_STATIC_OVERRIDES,
        CommonConfigurationKeys.HADOOP_USER_GROUP_STATIC_OVERRIDES_DEFAULT);
    Collection<String> mappings = StringUtils.getStringCollection(
        staticMapping, ";");
    Map<String, Set<String>> staticUserToGroupsMap = new HashMap<>();
    for (String users : mappings) {
      Collection<String> userToGroups = StringUtils.getStringCollection(users,
          "=");
      if (userToGroups.size() < 1 || userToGroups.size() > 2) {
        throw new HadoopIllegalArgumentException("Configuration "
            + CommonConfigurationKeys.HADOOP_USER_GROUP_STATIC_OVERRIDES
            + " is invalid");
      }
      String[] userToGroupsArray = userToGroups.toArray(new String[userToGroups
          .size()]);
      String user = userToGroupsArray[0];
      Set<String> groups = Collections.emptySet();
      if (userToGroupsArray.length == 2) {
        groups = new LinkedHashSet(StringUtils
            .getStringCollection(userToGroupsArray[1]));
      }
      staticUserToGroupsMap.put(user, groups);
    }
    staticMapRef.set(
        staticUserToGroupsMap.isEmpty() ? null : staticUserToGroupsMap);
  }

  private boolean isNegativeCacheEnabled() {

View on GitHub (pinned to 2add963021)

Solutions

1. Fix the value to the strict 'user=group1,group2;user2=group3' format: exactly one '=' per entry, entries separated by ';', no trailing separators
2. To map a user to no groups use the bare 'user' form (no '=' at all)
3. Escape or drop '=' characters inside group names; they cannot appear in this simple format
4. Restart the service after editing core-site.xml — the parse happens once in the Groups singleton

Example fix

# before (core-site.xml)
<property><name>hadoop.user.group.static.mapping.overrides</name>
  <value>alice=hdfs,users=bobs;bob=</value></property>

# after
<property><name>hadoop.user.group.static.mapping.overrides</name>
  <value>alice=hdfs,users;bob=hdfs</value></property>

static void validateStaticMapping(String v) {
  for (String entry : v.split(";")) {
    if (entry.isEmpty()) continue;
    String[] parts = entry.split("=", -1);
    if (parts.length > 2) {
      throw new IllegalArgumentException("Bad entry (multiple '='): " + entry);
    }
  }
}
String v = conf.get("hadoop.user.group.static.mapping.overrides", "");
validateStaticMapping(v);
new Groups(conf); // safe now

try {
  Groups.getUserToGroupsMappingService(conf);
} catch (HadoopIllegalArgumentException e) {
  // fix hadoop.user.group.static.mapping.overrides formatting
  LOG.error("Invalid static mapping overrides: {}", e.getMessage());
}

When it happens

Trigger: Config values like 'user=g1=g2' (two '=' signs, size 3), a trailing ';' producing an empty entry, or whitespace-only entries — StringUtils.getStringCollection yields malformed token counts. Any single bad entry poisons the whole property.

Common situations: Operators adding static overrides with '=' inside group DNs (LDAP-style 'CN=g,OU=x' unescaped); copy-paste from docs leaving 'user=' placeholders; scripts concatenating entries with stray semicolons; XML entity mistakes (& not escaped) truncating entries.

Related errors

• No scheme in default FS: ${uri}
• No more entry in " + f
• f + " is a directory"
• f + " already exists"
• Missing keyfile property ('%s') for authentication type '%s'

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